
## 一、文件类型与用途

| 文件 | 用途 | 提交Git |
|------|------|----------|
| `.env.example` | 配置模板，含占位符 | ✅ 是 |
| `.env` | 基础默认配置 | ❌ 否 |
| `.env.development` | 开发环境配置 | ✅ 是 |
| `.env.production` | 生产环境配置 | ✅ 是 |
| `.env.test` | 测试环境配置 | ✅ 是 |
| `.env.local` | 本地个人覆盖 | ❌ 否 |
| `.env.development.local` | 开发环境本地覆盖 | ❌ 否 |
| `.env.branch.<name>` | 特定分支配置（可选） | ❌ 否 |

## 二、加载优先级（从低到高）
系统环境变量 > .env.local > .env.[mode].local > .env.[mode] > .env
> 同名变量：高优先级覆盖低优先级
## 三、各框架差异速查

| 框架 | 客户端变量前缀 | 特殊文件 |
|------|---------------|----------|
| Next.js | `NEXT_PUBLIC_` | `.env.production.local` |
| Vite | `VITE_` | 无 |
| Laravel | 无（仅服务端） | `.env.testing` |
| Spring Boot | 需第三方库 | 配合 `application.yml` |

## 四、核心规则
1. **敏感信息不进Git** — 密钥、密码、Token 只放 `.gitignore` 涵盖的文件
2. **变量值默认为字符串** — 布尔/数字按字符串解析，框架可能有特殊处理
3. **客户端暴露需前缀** — 浏览器可访问的变量必须加特定前缀（如 `VITE_`、`NEXT_PUBLIC_`）

## 五、示例文件结构
project/
├── .env.example           # DB_HOST=localhost
├── .env                   # 实际配置（git ignored）
├── .env.development       # API_URL=http://dev.api
├── .env.production        # API_URL=https://api.com
├── .env.local             # 个人覆盖（git ignored）
└── .gitignore             # 包含 .env, *.local
## 六、常见反模式

| ❌ 错误做法 | ✅ 正确做法 |
|------------|------------|
| 将 `.env` 提交到 Git | 只提交 `.env.example` |
| 硬编码变量在代码中 | 通过环境变量读取 |
| 所有环境共用一个文件 | 按环境拆分文件 |
| 不设默认值 | `.env.example` 提供占位符 |
