在前端项目中，环境变量是团队协作和 CI/CD 流程的核心。无论是 Vue CLI 还是 Vite，都通过 .env 文件来管理不同环境下的配置。本文将详细讲解两者的差异、常用文件清单、使用方法和最佳实践。

---

🔑 为什么需要 .env 文件

• 统一配置：不同环境（开发、测试、生产）下的 API 地址、日志等级、功能开关。
• 安全隔离：敏感信息不直接写入代码，而是通过环境变量注入。
• 团队协作：不同成员可共享通用配置，同时保留个人私有配置。

---

📂 Vue CLI 项目中的 .env 文件

加载规则

• .env：所有模式都会加载。
• .env.development：仅在 vue-cli-service serve 时加载。
• .env.production：仅在 vue-cli-service build 时加载。
• .env.test：仅在 vue-cli-service test:unit 或 test:e2e 时加载。
• .env.local：本地私有，不提交到 Git。

命名规范

• 必须以 VUE_APP_ 前缀的变量才会暴露到客户端代码中。
• 其它变量（如 NODE_ENV）仅在构建时使用。

示例

# .env
VUE_APP_NAME=vue-cli-demo
VUE_APP_FEATURE_FLAG_LOGIN=true

# .env.development
NODE_ENV=development
VUE_APP_API_BASE=https://dev-api.example.com
VUE_APP_LOG_LEVEL=debug

# .env.production
NODE_ENV=production
VUE_APP_API_BASE=https://api.example.com
VUE_APP_LOG_LEVEL=warn

# .env.test
NODE_ENV=test
VUE_APP_API_BASE=https://test-api.example.com

代码中使用

console.log(process.env.VUE_APP_API_BASE);
if (process.env.NODE_ENV === 'development') {
  console.log('开发模式下开启调试工具');
}

---

📂 Vite 项目中的 .env 文件

加载规则

• .env：所有模式都会加载。
• .env.development：仅在 vite dev 时加载。
• .env.production：仅在 vite build 时加载。
• .env.test：测试环境。
• .env.local：本地私有，不提交到 Git。

命名规范

• 必须以 VITE_ 前缀的变量才会暴露到客户端代码中。
• 其它变量仅在构建时使用。

示例

# .env
VITE_APP_NAME=vite-demo
VITE_FEATURE_FLAG_LOGIN=true

# .env.development
NODE_ENV=development
VITE_API_BASE=https://dev-api.example.com
VITE_LOG_LEVEL=debug

# .env.production
NODE_ENV=production
VITE_API_BASE=https://api.example.com
VITE_LOG_LEVEL=warn

# .env.test
NODE_ENV=test
VITE_API_BASE=https://test-api.example.com

代码中使用

console.log(import.meta.env.VITE_API_BASE);
if (import.meta.env.MODE === 'development') {
  console.log('开发模式下开启调试工具');
}

---

📌 团队实践推荐的扩展文件

文件名	使用场景
.env.staging	预发布/灰度环境
.env.ci	CI/CD 流水线专用
.env.preview	演示环境

---

🛡️ 最佳实践与安全建议

• 敏感信息隔离：API 密钥、数据库密码放在 .env.local 或 CI/CD 注入，不提交到仓库。
• 模式明确：构建时显式指定 --mode，避免加载错误的配置。
• 统一前缀：Vue CLI 用 VUE_APP_，Vite 用 VITE_，避免混淆。
• 版本控制策略：
  • 提交 .env、.env.development、.env.production、.env.test、.env.staging。
  • 忽略 .env.local、.env.ci、.env.preview。

---

✅ 总结

• Vue CLI 与 Vite 都支持 .env 文件，但前缀不同：VUE_APP_ vs VITE_。
• .env 文件用于通用配置，.env.{mode} 用于环境特定配置，.env.local 用于个人敏感配置。
• 团队可扩展 .env.staging、.env.ci、.env.preview 来覆盖更多场景。
• 最佳实践是 敏感信息不入库，构建模式显式指定，前缀统一，提交策略清晰。