Next.js NEXT_PUBLIC环境变量在Azure静态Web应用中无法读取

一、Next.js环境变量核心区别 #

• 服务端私有变量：无NEXT_PUBLIC_前缀，仅在Node.js运行环境（API路由、getServerSideProps、getStaticProps等服务端逻辑）中可读取，不会被打包进前端代码，用于存储客户端密钥、数据库连接串等敏感信息。
• 前端公共变量：必须以NEXT_PUBLIC_为前缀，构建阶段会被注入到前端代码，客户端组件、浏览器环境均可直接访问，适合存放API基础地址、第三方SDK公钥等公开配置。

二、Azure部署下NEXT_PUBLIC变量失效的解决步骤 #

1. 确认Azure配置与应用重启
   • 检查Azure「配置->应用设置」中的变量名，确保严格遵循NEXT_PUBLIC_XXX格式，注意大小写（Next.js对变量名大小写敏感）。
   • 应用设置修改后必须重启Azure应用服务，否则新变量不会生效，生产环境尤其需要注意这一点。
2. 保证构建阶段能读取变量
   • Next.js的公共环境变量是在构建时注入前端代码的，而非运行时。如果是通过GitHub Actions或Azure DevOps自动化部署，务必让构建过程在Azure环境内执行，确保构建时能读取到Azure配置的NEXT_PUBLIC_变量。
   • 禁止本地构建后上传代码到Azure：本地构建时若未配置对应变量，前端代码不会包含该变量，上传后自然返回undefined。
3. 验证变量注入情况
   • 在前端组件中打印process.env（客户端环境下仅会显示NEXT_PUBLIC_前缀的变量），或者查看打包后的静态JS文件，搜索是否存在目标变量值，确认是否成功注入。

三、额外注意事项 #

• 敏感信息绝对不能使用NEXT_PUBLIC_前缀，即便服务端能读取这类变量，但它们会被暴露在前端代码中。
• 若使用Azure Static Web Apps部署Next.js，需在staticwebapp.config.json中配置环境变量，或在部署流水线的环境变量中添加，确保构建阶段可获取。

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