本文旨在解决react应用在生产构建后，`.env`文件中定义的api或配置变量无法正确读取（显示为`NULL`）的问题。我们将探讨react环境变量的工作原理，分析常见的导致生产环境变量失效的原因，并提供一个具体的解决方案——通过在访问`process.env`变量时使用括号包裹来确保其正确解析，同时给出部署在nginx环境下的注意事项。
在开发React应用时，我们经常使用.env文件来管理环境变量，例如API地址、密钥等。这些变量通常通过process.env.REACT_APP_YOUR_varIABLE的形式在代码中访问。然而，一个常见的挑战是，当应用被构建并部署到生产环境时，这些变量有时会神秘地显示为null或未定义，导致应用功能异常。本教程将深入探讨这一问题，并提供一个具体的解决方案。
React应用中环境变脸的工作机制
理解React应用中环境变量的工作方式是解决问题的关键。
- 构建时注入： 与服务器端应用不同，React（特别是通过Create React App或类似的webpack配置）中的环境变量并非在运行时从服务器环境中读取。相反，它们是在构建时被注入到最终的javaScript包中的。这意味着，当你运行npm run build时，Webpack会查找所有process.env.REACT_APP_开头的变量，并将其替换为.env文件中或构建环境中实际的字符串值。
- REACT_APP_前缀： 为了避免与系统环境变量冲突，Create React App要求所有自定义的环境变量都必须以REACT_APP_为前缀。没有此前缀的变量将不会被Webpack识别并注入到客户端代码中。
- 最终产物： 生产构建后的javascript文件中，process.env.REACT_APP_API这样的表达式将不复存在，取而代之的是其在构建时被替换的实际字符串值。例如，如果REACT_APP_API=https://api.example.com，那么在打包后的代码中，你将直接看到”https://api.example.com”。
生产环境.env变量读取失败的常见原因
当process.env变量在生产环境中显示为null时，通常有以下几个原因：
- .env文件在构建时缺失或未被正确加载： 这是最常见的原因。确保在执行npm run build命令的服务器或CI/CD环境中，.env文件存在于项目根目录，并且可被构建工具访问。
- 变量命名不符合规范： 变量没有以REACT_APP_开头。
- 缓存问题： 浏览器或CDN缓存了旧版本的JavaScript文件，其中不包含正确的环境变量。
- CI/CD管道配置不当： 自动化构建流程（如gitLab CI/CD）未将环境变量正确传递给构建命令，或者环境变量被覆盖。
- Webpack或其他打包工具配置问题： 自定义Webpack配置可能干扰了默认的环境变量处理机制。
案例分析与特定解决方案
在一个使用gitlab CI构建React应用并部署到nginx的场景中，用户发现即使.env文件存在于项目根目录，并且变量命名符合REACT_APP_规范，但在生产构建后，process.env.REACT_APP_API和process.env.REACT_APP_CODE仍然显示为null。
以下是原始代码片段：
import axios, { CancelTokenSource } from "axios"; const queryCors = "http://localhost:3005"; // 这是一个本地开发用的硬编码值，与问题无关 const headers = { Accept: "application/json", api: process.env.REACT_APP_API, // 这里的环境变量未能正确读取 code: process.env.REACT_APP_CODE // 这里的环境变量未能正确读取 };核心解决方案： 用户通过在访问process.env变量时，使用括号将其包裹起来，成功解决了这个问题。
修复后代码示例：
import axios, { CancelTokenSource } from "axios"; const queryCors = "http://localhost:3005"; const headers = { Accept: "application/json", API: (process.env.REACT_APP_API), // 注意：这里使用了括号包裹 code: (process.env.REACT_APP_CODE) // 注意：这里使用了括号包裹 };解释： 尽管将process.env.VAR用括号包裹并不是标准的环境变量访问模式，但在某些特定的构建环境、JavaScript解析器版本或Babel/Webpack插件配置下，这种显式的分组操作可能有助于确保process.env表达式在编译或运行时被正确评估和替换。它可能避免了某些Linter或编译器在处理对象字面量中未包裹的process.env表达式时产生的副作用，从而强制其作为一个独立的表达式被优先处理。如果遇到类似问题，尝试这种方法可能是一个有效的调试方向。
Nginx部署环境下的注意事项
当React应用构建完成后，它会生成一系列静态文件（html, css, JS等），这些文件通常通过Nginx这样的静态文件服务器进行部署。
-
Nginx不处理.env： Nginx作为静态文件服务器，不会在运行时解析或处理.env文件。所有环境变量的值都必须在React应用构建时就已经被注入到JavaScript文件中。
-
确保构建产物正确： 部署到Nginx的应该是已经包含了正确环境变量值的构建产物。
-
Nginx配置示例： 提供的Nginx配置片段是典型的React应用部署配置，它确保了所有路由请求最终都会回退到index.html，这对于客户端路由是必需的。
location / { root /var/www/website; # 指向你的React应用构建产物目录 index index.html index.htm; try_files $uri $uri/ /index.html; # 确保客户端路由正常工作 }
总结与最佳实践
解决React应用生产环境环境变量读取问题，关键在于理解其构建时注入的特性。
- 构建时可用性： 始终确保.env文件在构建过程中是可用的。
- 命名规范： 遵循REACT_APP_前缀约定。
- CI/CD管理： 在自动化构建流程中，明确地管理和传递环境变量。例如，在GitLab CI中，可以使用CI/CD变量来存储敏感信息，并在构建脚本中将其作为环境变量提供。
- 调试技巧： 如果遇到问题，可以通过以下方式进行调试：
- 尝试特定解决方案： 如果标准方法无效，可以尝试本文中提及的，用括号包裹process.env.YOUR_VAR的方法，这可能解决某些特定环境下的解析问题。
通过上述方法，您可以有效地排查并解决React应用在生产环境中环境变量读取失败的问题，确保应用稳定运行。