@tianyio/quality-helper/templates/configs/docs/环境配置说明文档.md

A comprehensive quality helper tool for project scaffolding and management

# 环境配置说明文档

## 目录结构

```
env/
├── .env.develop        # 开发环境
├── .env.test           # 测试环境
├── .env.pre            # 预发布环境
└── .env.prod           # 生产环境
```

## 环境分类

### 开发环境

- 开发环境: `.env.develop`

### 测试环境

- 测试环境: `.env.test`

### 预发布环境

- 预发布环境: `.env.pre`

### 生产环境

- 生产环境: `.env.prod`

## 配置变量说明

### 通用配置

| 变量名         | 说明     | 示例     |
| -------------- | -------- | -------- |
| VITE_APP_TITLE | 应用标题 | 'My App' |

### 服务地址配置

| 变量名            | 说明         | 示例                        |
| ----------------- | ------------ | --------------------------- |
| VITE_API_BASE_URL | API 基础地址 | 'http://localhost:3000/api' |

### 前端资源配置

| 变量名           | 说明         | 示例 |
| ---------------- | ------------ | ---- |
| VITE_PUBLIC_PATH | 静态资源路径 | '/'  |

## 使用方式

### 开发环境

```bash
# 启动开发环境
pnpm dev

# 启动指定环境
pnpm dev --mode develop
```

### 构建环境

```bash
# 构建生产环境
pnpm build

# 构建指定环境
pnpm build --mode prod

# 构建并分析产物
ANALYZE=true pnpm build
```

## 配置加载机制

1. 环境配置文件在构建时自动加载
2. Vite 通过 `loadEnv` 函数加载对应环境的配置
3. 配置变量以 `VITE_` 为前缀，避免冲突
4. 环境变量在应用中通过 `import.meta.env` 访问

## 环境配置验证机制

### 验证脚本

项目提供了自动化的环境配置验证机制，确保所有环境配置文件的完整性和正确性。

### 使用方法

```bash
# 验证所有环境配置文件
pnpm env:validate

# 验证特定环境配置文件
pnpm env:validate .env.develop
```

### 验证内容

1. **文件存在性检查** - 确保所有必需的环境配置文件都存在
2. **必需变量检查** - 根据环境类型验证必需变量是否定义
3. **格式验证** - 检查配置文件格式是否正确
4. **URL格式验证** - 验证URL类型变量的格式是否正确

### 验证规则

- 所有环境变量必须采用 `KEY=VALUE` 格式
- URL类型的变量必须符合URL格式规范

### 代码提交时自动验证

项目配置了代码提交时的自动环境配置验证机制：

1. 当环境配置文件被修改并添加到 Git 暂存区时，会自动运行验证脚本
2. 验证失败会阻止代码提交
3. 确保环境配置的正确性和一致性

## 最佳实践

1. **环境隔离**: 不同环境使用独立的配置文件
2. **敏感信息**: 避免在配置文件中存储敏感信息
3. **版本控制**: 环境配置文件应纳入版本控制
4. **文档同步**: 配置变更时及时更新本文档
5. **定期验证**: 定期运行验证脚本确保配置正确性
6. **性能配置**: 根据环境合理配置性能监控参数
7. **提交前验证**: 利用 Git Hooks 机制确保配置正确性