React/Node项目中process.env.SOME_VARIABLE定义位置排查求助

Node 端排查步骤 #

• 确认是否安装并启用了dotenv：Node本身不会自动加载.env文件，必须通过dotenv库实现。检查项目依赖里有没有dotenv，代码里是否在引用变量前执行了require('dotenv').config()。
• 核对.env文件路径：必须放在项目根目录（和package.json同级），如果放在子目录，需要在config方法里指定路径，比如require('dotenv').config({ path: './config/.env' })。
• 检查变量格式：.env里的变量要写成KEY=VALUE的格式，不要给值加多余的引号（除非值包含特殊字符），变量名前后不能有空格。
• 查看启动命令：有没有在启动脚本里通过命令行加载变量，比如node -r dotenv/config index.js，或者用cross-env注入变量，这种情况不需要手动在代码里require dotenv。
• 检查系统环境变量：直接在终端执行echo $SOME_VARIABLE，看变量是不是直接设置在系统环境里，而非项目的.env文件。
• 确认环境对应的.env文件：如果项目有.env.development、.env.production这类环境专属文件，要确认当前启动的环境加载的是对应文件，这类文件的优先级高于通用.env。
• 检查代码执行顺序：dotenv.config()必须放在所有引用process.env变量的代码之前，否则变量还没注入就被读取了。

React 端排查步骤 #

• 检查变量前缀：用Create React App（CRA）创建的项目，环境变量必须以REACT_APP_开头，比如REACT_APP_SOME_VARIABLE，不然不会被注入到前端的process.env中。
• 确认.env文件位置：同样要放在项目根目录，和package.json、public文件夹同级。
• 重启开发服务器：修改.env文件后必须重启React的dev server，新变量才会生效。
• 核对构建工具规则：如果是eject后的CRA项目，或者用了Vite等其他工具，变量规则会有差异。比如Vite中要使用import.meta.env.VITE_SOME_VARIABLE，前缀是VITE_，且不用process.env。
• 检查环境专属文件：CRA会根据当前环境加载对应的.env文件，比如开发环境加载.env.development，生产环境加载.env.production，这些文件里的变量会覆盖通用.env的内容。
• 生产构建注意事项：生产构建时变量是在构建阶段注入的，要确保构建前对应环境的变量已正确配置，不管是写在.env文件还是系统环境里。

通用排查技巧 #

• 打印所有环境变量：在Node代码里加console.log(process.env)，在React组件里加console.log(process.env)（React端只能看到符合规则的变量），直接查看输出里有没有目标变量。
• 检查.gitignore配置：确认是不是.env文件被忽略没提交到代码库，或者有其他.env.*文件被忽略导致本地缺失。
• 查看CI/CD配置：如果是部署环境找不到变量，可能是CI/CD平台（比如GitHub Actions、GitLab CI）里单独配置了环境变量，没有写在本地.env文件中。
• 检查package.json脚本：启动脚本里可能直接注入了变量，比如"start": "SOME_VARIABLE=xxx react-scripts start"，这种情况下变量不会出现在.env文件里。

内容的提问来源于stack exchange，提问作者red_wolf