适用场景:前端(Vite、Vue CLI/Webpack、CRA、Next.js、Nuxt)、Node.js 服务端、容器化(Docker/K8s)、CI/CD。涵盖 构建时 vs 运行时、命名约定、优先级与加载顺序、安全与密钥管理、跨平台、类型校验 等。
TL;DR 要点(快速总结)
- 构建时(Build-time)与运行时(Runtime)必须分清:多数前端框架会在构建时把环境变量写进打包产物,部署后改
.env不会生效。若需要部署后能改,用运行时注入(env.js/config.json/ Nginxenvsubst)。 - 前端暴露即不安全:凡放到浏览器的变量都不是秘密(API 域名、feature 开关可以,密钥或 token 绝不可)。
- 命名前缀:不同框架用不同前缀暴露给前端(
VITE_、VUE_APP_、REACT_APP_、NEXT_PUBLIC_、Nuxt 的runtimeConfig.public)。 - 优先级与加载顺序:一般
.env.local>.env.[mode]>.env> 系统环境;但不同工具略有差别。 - 类型校验:使用
envalid、zod在启动时校验,能大幅降低拼写错误或缺失导致的线上故障。 - CI/Secrets/容器:把密钥放在 CI/Secrets 或 Secret Manager(Vault、AWS Secrets Manager),不要提交到仓库或打包进前端产物。
2025/5/1大约 7 分钟
