`.env.development修改后未生效？`

Question

在使用 `.env.development` 文件配置环境变量时，经常遇到修改后未生效的问题。通常，这类问题的原因有以下几点：一是环境变量未正确加载，如未使用 `dotenv` 或其他环境变量加载库；二是变量命名不符合规范，例如未以 `REACT_APP_`（React项目）或 `VITE_`（Vite项目）开头；三是修改后未重启开发服务器，导致旧缓存变量依然生效；四是不同环境文件（如 `.env.production`）被错误加载。排查时应检查变量命名、加载逻辑及运行时环境，确保配置正确生效。

Answer 1

一、问题概述：环境变量修改未生效

在现代前端项目中，使用 .env.development 文件配置环境变量是一种常见做法。然而，在实际开发过程中，常常出现修改环境变量后并未生效的问题。这不仅影响调试效率，也可能导致部署错误。

二、常见原因分析

• 环境变量未正确加载：如未使用 dotenv 或未正确配置加载逻辑。
• 变量命名不规范：如未以 REACT_APP_（React）或 VITE_（Vite）开头。
• 开发服务器未重启：修改后未重启服务，导致旧变量缓存仍在使用。
• 错误加载环境文件：如本应加载 .env.development，却加载了 .env.production。

三、排查流程图

      graph TD
      A[开始排查] --> B{是否使用dotenv或框架支持?}
      B -- 是 --> C{变量名是否符合规范?}
      C -- 是 --> D{是否重启开发服务器?}
      D -- 是 --> E{加载的是正确的.env文件吗?}
      E -- 是 --> F[环境变量应已生效]
      E -- 否 --> G[检查文件名和环境模式]
      D -- 否 --> H[重启开发服务器]
      C -- 否 --> I[修改变量名为REACT_APP_或VITE_开头]
      B -- 否 --> J[引入dotenv或使用框架内置支持]
    

四、解决方案与最佳实践

1. 确认环境变量加载机制：
   • React项目：使用 dotenv，默认支持 .env.development。
   • Vite项目：内置支持 .env 和 .env.development，变量需以 VITE_ 开头。
   • 手动加载示例代码：

     require('dotenv').config({ path: '.env.development' });

2. 变量命名规范：

   框架	变量前缀	示例
   React (Create React App)	REACT_APP_	REACT_APP_API_URL
   Vite	VITE_	VITE_API_KEY

3. 开发服务器重启：

   修改环境变量后必须重启开发服务器，否则 Node.js 缓存可能保留旧值。建议使用 npm run dev 或 npm run start 前先 Ctrl+C 停止服务。

4. 确认加载的环境文件：
   • React项目：根据 npm start 时的 NODE_ENV 加载对应文件。
   • Vite项目：根据 mode 参数加载对应文件，如 vite --mode development。

五、进阶调试技巧

对于高级开发者，可以通过以下方式进一步验证环境变量是否生效：

• 在项目入口文件中打印 process.env 查看加载的变量。
• 使用 console.log(import.meta.env) 在 Vite 项目中查看变量。
• 通过 DEBUG=dotenv node app.js 查看 dotenv 的加载过程。