Docker部署至AWS App Runner的NextJS应用无法识别环境变量求助

1. 优先确认构建阶段环境变量注入链路 #

NEXT_PUBLIC_前缀的环境变量为NextJS客户端公开变量，会在应用构建阶段直接硬编码到静态资源包，运行时注入的变量不会更新这部分值，这是绝大多数同类问题的根因：

• 如果你是本地构建镜像后推送到AWS容器注册表再部署到App Runner，本地构建时没有传入对应NEXT_PUBLIC_变量的话，部署后所有公开变量都会是undefined，建议将镜像构建环节转移到App Runner自动构建，或在CI/CD构建镜像的阶段通过--build-arg传入所有公开变量
• 多阶段Dockerfile中注意变量传递逻辑，ARG参数仅在当前构建阶段生效，需要赋值给ENV才能被NextJS构建流程读取，参考正确写法：

# 接收构建参数
ARG NEXT_PUBLIC_API_URL
# 赋值为环境变量供NextJS构建读取
ENV NEXT_PUBLIC_API_URL=$NEXT_PUBLIC_API_URL

• 不带NEXT_PUBLIC_前缀的服务端变量为运行时读取，不需要在构建阶段传入，只需在App Runner运行时配置即可。

2. 验证App Runner配置正确性 #

• 确认环境变量键名完全匹配，不要出现大小写错误、多余空格、NEXT_PUBLIC_前缀拼写错误
• 配置变量值时不要额外包裹单引号/双引号，App Runner会将引号识别为值的一部分，导致程序读取异常
• 修改变量配置后必须手动触发App Runner服务重新部署，仅保存配置不会生效

3. 临时调试验证注入结果 #

• 修改Docker启动命令，先打印容器内全量环境变量后再启动服务，比如将启动命令调整为printenv && npm start，查看App Runner运行日志确认你配置的变量是否真的注入到了容器运行环境
• 服务端变量可以在getServerSideProps等服务端执行逻辑中加临时日志打印process.env对应字段，确认服务端读取结果
• 客户端公开变量可以直接在浏览器控制台打印process.env.NEXT_PUBLIC_XXX，确认构建阶段是否正确注入

4. 其他异常场景排查 #

• 检查next.config.js中是否配置了env字段覆盖了传入的环境变量
• 如果开启了NextJS静态导出配置output: 'export'，所有环境变量仅能在构建阶段读取，运行时注入的所有变量都不会生效
• 确认NextJS版本无已知环境变量读取Bug，12.0及以上正式版本对环境变量的处理逻辑相对稳定。

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