1. 环境变量在前端工程中的核心作用第一次接触环境变量时我完全不明白为什么要在代码里搞这些神秘参数。直到某个深夜我在紧急修复生产环境bug时不小心把本地开发的mock数据接口打到了线上服务器——那次事故让我彻底理解了环境隔离的重要性。环境变量本质上是运行时的动态配置参数就像给程序装了个智能开关。举个例子你的开发环境可能连接本地的http://localhost:3000/api而生产环境需要指向https://api.yourdomain.com。通过process.env.API_URL这样的变量代码无需修改就能自动适应不同环境。在Node.js体系中process.env是个特别的对象。你可以直接在Node REPL里试试node process.env这会输出一长串系统信息包括PATH、HOME等系统变量。但注意NODE_ENV这个前端常用的变量默认是不存在的需要我们自己配置。这也是为什么新手常常遇到process.env.NODE_ENV返回undefined的困惑。2. 跨平台配置方案cross-env实战2.1 为什么需要cross-env五年前我在Windows上开发时发现同事在Mac上能跑的脚本在我这儿总是报错。原来是因为设置环境变量的语法差异# Windows set NODE_ENVproduction webpack # Mac/Linux NODE_ENVproduction webpack这就是cross-env要解决的问题。它像是个翻译官让环境变量设置命令在不同操作系统上表现一致。安装起来很简单npm install cross-env --save-dev2.2 完整配置示例现代前端项目通常这样配置package.json{ scripts: { dev: cross-env NODE_ENVdevelopment webpack serve --open, build:stage: cross-env NODE_ENVstaging webpack --progress, build:prod: cross-env NODE_ENVproduction webpack --profile } }我曾经遇到过一个问题在Docker容器中运行时cross-env设置的值无法传递。后来发现需要在Dockerfile中加入ENV NODE_ENVproduction2.3 全局变量注入技巧在webpack配置中我推荐使用DefinePlugin进行全局注入const webpack require(webpack); module.exports { plugins: [ new webpack.DefinePlugin({ process.env.API_ENDPOINT: JSON.stringify(process.env.API_URL || /api) }) ] }这样在业务代码中可以直接使用fetch(${process.env.API_ENDPOINT}/users)3. 进阶方案.env文件体系3.1 文件命名规范演化史早期项目可能只有一个.env文件但现代工程更推荐多环境方案.env # 基础默认配置 .env.local # 本地覆盖配置不应提交到git .env.development # 开发环境专用 .env.test # 测试环境 .env.production # 生产环境有个实际案例某次CI构建失败就是因为测试同学误将.env.test提交成了.env。所以务必在.gitignore中加入.env .env.local3.2 安全加载策略使用dotenv加载时要注意加载顺序require(dotenv).config() // 加载.env require(dotenv).config({ path: .env.${process.env.NODE_ENV} })我曾踩过一个坑在Next.js项目中服务端代码和客户端代码的环境变量处理方式不同。解决方案是// next.config.js module.exports { env: { CLIENT_SIDE_VAR: process.env.CLIENT_SIDE_VAR } }3.3 变量命名最佳实践建议采用前缀命名法避免冲突# 正确示范 VUE_APP_API_URLhttps://api.example.com REACT_APP_SECRET_KEY123456 # 不推荐 API_URLhttps://api.example.com # 可能被系统变量覆盖在TypeScript项目中可以添加类型声明declare namespace NodeJS { interface ProcessEnv { readonly NEXT_PUBLIC_API_URL: string readonly DATABASE_URL: string } }4. 多环境治理方案4.1 动态配置加载器我开发过一个动态加载器能根据git分支自动选择环境const branch require(git-branch).sync() const envFile .env.${branch main ? production : branch} require(dotenv).config({ path: envFile })4.2 CI/CD集成实践在GitLab CI中可以这样使用build: stage: build script: - cp .env.${CI_ENVIRONMENT_NAME} .env - npm run build4.3 敏感信息处理方案永远不要将敏感信息直接写在.env文件中推荐的做法使用vault服务管理密钥开发时通过export KEYvalue临时设置在CI中配置Secret Variables5. 常见陷阱与解决方案5.1 缓存导致变量未更新Next.js等框架会有编译缓存修改.env后需要rm -rf .next npm run dev5.2 变量类型转换问题环境变量永远都是字符串类型需要手动转换const MAX_ITEMS parseInt(process.env.MAX_ITEMS || 10)5.3 客户端暴露风险前端代码中直接使用process.env会导致变量暴露。解决方案// webpack配置 new webpack.DefinePlugin({ process.env.SAFE_VAR: JSON.stringify(value) })6. 现代方案对比选型6.1 方案对比表特性cross-env.env文件运行时注入适用场景简单项目多环境项目云原生部署安全性较低中等高维护成本低中高团队协作友好度差优良6.2 我的技术选型建议对于新启动的项目我现在的标准做法是开发环境使用.env.development测试环境使用CI注入变量生产环境使用K8s ConfigMap在Monorepo项目中可以在各子项目根目录放置.env文件同时在最外层设置公共变量# packages/web/.env SHARED_API_URL$ROOT_API_URL/client