原因诊断
生产环境中 env 变量读取为 null 的常见原因
在生产打包后的 React 应用中，环境变量通常是在构建时注入的，浏览器环境无法动态读取 .env 文件。因此，变量变为 null 或 undefined，往往与构建阶段的注入失败有关。
一个常见原因是变量命名错误或前缀不一致，例如 CRA 需要 REACT_APP_ 前缀，而 Vite 使用 VITE_ 前缀。若变量未使用正确前缀，构建时不会被注入，运行时就会看到 null/undefined。
# CRA/Cra 变量示例（生产环境）
# 需要在 .env.production 中定义
REACT_APP_API_BASE_URL=https://api.example.com
另一个原因是在 CI/CD 流水线中未将变量注入到构建命令或环境中，导致打包时变量为 null 或 undefined。
# 构建命令示例（请确保在构建时导出变量）
REACT_APP_API_BASE_URL=https://api.example.com npm run build
完整排查与解决方案
逐步排查清单与日常工作流
下面的排查清单用于系统定位生产环境变量读取为 null 的根本原因，每一步都要在控制台输出关键变量值进行对比。
第一步，确认构建工具及变量前缀是否匹配，例如 CRA 使用 REACT_APP_，Vite 使用 VITE_。
// CRA 示例：读取变量
const apiBase = process.env.REACT_APP_API_BASE_URL;
console.log('API_BASE', apiBase); // 应不为 null
第二步，检查 .env.production 是否存在，并确认变量是否被正确写入文件中。
# 典型 .env.production
REACT_APP_API_BASE_URL=https://api.example.com
第三步，在构建环境中确保变量被注入，若在 CI/CD 中构建，请在环境变量设置处明确写入。
# CI 环境变量示例（伪代码）
env:global:- REACT_APP_API_BASE_URL=https://api.example.com
第四步，确认在浏览器端使用正确的读取方式，若使用 Vite，应使用 import.meta.env，而非 process.env。
// Vite 示例
const apiBase = import.meta.env.VITE_API_BASE_URL;
console.log('API_BASE', apiBase);
第五步，确保变量在打包后的产物中确实被替换，你可以在构建产物中查找输出的变量值是否被替换成对应的字符串。
# 查看打包后的代码（示例路径可能不同）
grep -R "VITE_API_BASE_URL" dist/ -n
解决方案落地：从开发到生产的完整做法
在完成诊断后，将变量注入和读取流程统一在构建阶段完成，避免在运行时动态依赖 .env 文件，这也是防止 production 读取为 null 的关键。
// 使用代理变量替换示例
export const API_BASE_URL = process.env.REACT_APP_API_BASE_URL || 'https://fallback.example.com';
下面给出两种主流构建工具的正确配置示例，以确保生产环境中 env 变量不会为 null：
# CRA 的正确配置
# .env.production
REACT_APP_API_BASE_URL=https://api.example.com# 构建命令
REACT_APP_API_BASE_URL=https://api.example.com npm run build
# Vite 的正确配置
# .env.production
VITE_API_BASE_URL=https://api.example.com# 构建命令（变量在构建时注入）
VITE_API_BASE_URL=https://api.example.com npm run build
若你的应用是服务器端渲染（如 Next.js），处理方式会略有不同，请确保服务器端变量仅在构建时注入，并在客户端暴露前进行必要的安全控制。
// Next.js 客户端读取示例
const apiBase = process.env.NEXT_PUBLIC_API_BASE_URL;
