Next.js项目环境变量无法读取问题求助（含Docker配置提示）

问题描述 #

在Next.js项目中设置环境变量后无法正常读取，添加了以下日志代码：

console.log('env', process.env.NODE_ENV);
console.log('backend url', process.env.BACKEND_URL);

默认运行时输出符合预期：

env development
backend url undefined

尝试了多种设置方式均无效：

1. 直接赋值变量

NODE_ENV=production
BACKEND_URL=url

结果：输出旧值，同时出现警告：⚠ You are using a non-standard "NODE_ENV" value in your environment. This creates inconsistencies in the project and is strongly advised against.

2. 使用export命令

export NODE_ENV=production
export BACKEND_URL=url

结果：同上，输出旧值并显示警告

3. 运行npm run dev时前置变量

BACKEND_URL=url NODE_ENV=production npm run dev 

结果：echo能正确显示变量，但代码中仍输出development和undefined

4. 使用.env文件

NODE_ENV=production
BACKEND_URL=url

结果：服务器提示已读取.env文件，但问题依旧

额外检查了~/.bashrc和~/.zshrc，未发现相关变量设置。

可能的原因及解决办法 #

1. Next.js对NODE_ENV的强制覆盖 #

Next.js会根据运行命令自动设置NODE_ENV：

• 执行npm run dev时，框架强制将NODE_ENV设为development，手动设置的值会被覆盖，这也是警告的来源
• 要使用production环境，必须先执行npm run build完成打包，再执行npm start启动生产服务器，此时NODE_ENV会自动设为production

2. 客户端环境变量命名限制 #

如果你的代码是在客户端组件中读取BACKEND_URL，Next.js要求客户端可访问的环境变量必须以NEXT_PUBLIC_开头。将变量名改为NEXT_PUBLIC_BACKEND_URL，无论是通过命令行前置还是.env文件设置，都能正常读取。

3. 开发服务器缓存问题 #

Next.js开发服务器可能缓存了旧的环境变量，解决方法：

• 停止当前服务器进程
• 删除项目根目录下的.next文件夹
• 重新启动开发服务器，加载最新的环境变量

4. .env文件的环境匹配问题 #

Next.js会根据当前环境自动加载对应后缀的.env文件：

• 开发环境对应.env.development
• 生产环境对应.env.production
  将变量写入对应环境的文件中，避免手动切换出错。

补充：Docker环境注意事项 #

如果在Docker中部署，必须在构建镜像前设置环境变量，或在Dockerfile中用ENV指令声明变量，否则构建阶段无法读取到变量值。

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