Azure Web App中Next.js应用的服务端环境变量无法正常工作

核心问题分析 #

你遇到的情况是：本地.env.local里的服务端环境变量正常可用，但Azure配置的同名变量在Next.js服务端上下文始终返回undefined；用next.config.js的env字段虽能读取到值，但会把敏感变量暴露给客户端——这是因为该字段是Next.js v9之前的旧方案，会将变量打包进客户端代码，完全不适合存储API密钥这类敏感信息。

解决方案步骤 #

1. 确认Azure App Service的环境变量已正确注入 #

• 登录Azure门户，进入你的App Service，打开「配置」>「应用程序设置」，确认API_CLIENT_SECRET已存在，且键值对完全匹配（注意process.env大小写敏感，不要出现拼写错误）。
• 如果是通过变量组关联的配置，确保变量组已同步到App Service，完成配置后点击「保存」并重启App Service（环境变量变更需重启才能生效）。

2. 移除next.config.js中的env配置块 #

这个旧方式会强制将变量注入客户端bundle，无论是否带有NEXT_PUBLIC_前缀，直接删除该配置：

module.exports = {
  reactStrictMode: true,
  output: "standalone",
  // 移除以下env配置块
  // env: {
  //   API_CLIENT_SECRET: process.env.API_CLIENT_SECRET,
  // },
}

3. 验证服务端环境变量的可用性 #

创建一个临时API路由测试服务端是否能读取变量（该路由完全在服务端运行，不会暴露给客户端）：

Pages Router 写法（pages/api/test-env.js）

export default function handler(req, res) {
  // 仅验证变量是否存在，不要直接返回变量值
  res.status(200).json({
    hasSecret: !!process.env.API_CLIENT_SECRET,
    note: '敏感变量不会被返回给客户端'
  });
}

App Router 写法（app/api/test-env/route.js）

export async function GET() {
  return Response.json({
    hasSecret: !!process.env.API_CLIENT_SECRET,
    note: '敏感变量不会被返回给客户端'
  });
}

部署后访问该接口，若返回hasSecret: true，说明服务端已能正常读取变量。

4. 排查部署流程的潜在问题 #

• 若使用Azure Deployment Center（如GitHub Actions）部署，检查部署脚本中是否有覆盖环境变量的操作，比如CI/CD流程中设置了同名但值为空的变量。
• 确认Next.jsstandalone输出模式的部署包完整，Azure App Service会自动处理依赖，但如果有自定义部署脚本，需确保没有遗漏环境变量的注入逻辑。

关键注意事项 #

• 服务端专用的环境变量绝对不要加NEXT_PUBLIC_前缀，该前缀是专门用来将变量暴露给客户端的标记。
• 永远不要在客户端组件（包括渲染逻辑、客户端钩子）中访问敏感变量，哪怕是打印日志，都可能被浏览器DevTools捕获。

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