如何为AWS Amplify托管的Next.js应用配置环境变量？

问题背景 #

在AWS Amplify托管的Next.js应用中，前端通过process.env.NEXT_PUBLIC_SOME_KEY访问环境变量，已在Amplify控制台「环境变量」中添加对应变量，但按照文档修改构建脚本后出现构建报错，需实现前后端环境变量的正确配置。

核心规则：Next.js环境变量分类 #

Next.js对环境变量的访问权限有明确区分，配置时必须遵守：

• 前端可访问变量：变量名必须以NEXT_PUBLIC_为前缀，构建阶段会被注入到静态资源中，客户端组件可直接读取
• 后端专属变量：变量名无需加前缀，仅在SSR页面、API路由、Server Components等服务器端运行的代码中可用，不会暴露到前端

步骤1：AWS Amplify控制台配置变量 #

1. 进入Amplify应用的「环境设置」→「环境变量」页面
2. 添加变量：
   • 前端变量：直接输入NEXT_PUBLIC_SOME_KEY=你的值，无需额外配置
   • 后端变量：输入PRIVATE_API_KEY=你的敏感值，不要勾选「将变量暴露给前端构建」，防止敏感信息泄露
3. 保存配置，触发重新构建

步骤2：构建脚本正确配置（避免报错关键） #

Next.js在Amplify部署时，无需手动在构建脚本中导出环境变量——Amplify会自动将控制台配置的变量注入到构建环境中，之前的报错是因为错误添加了冗余的导出语句（如export NEXT_PUBLIC_SOME_KEY=$NEXT_PUBLIC_SOME_KEY）导致语法错误。

正确的构建脚本直接使用Next.js默认命令即可：

npm run build

或使用yarn：

yarn build

若确实需要自定义构建流程（如额外预处理），需保证语法正确，示例：

export NEXT_PUBLIC_SOME_KEY=$NEXT_PUBLIC_SOME_KEY && npm run build

但注意：此步骤完全多余，Next.js会自动读取环境变量，建议直接使用默认构建命令。

步骤3：代码中验证变量 #

• 前端组件中使用：

// 客户端组件
export default function Home() {
  return <div>{process.env.NEXT_PUBLIC_SOME_KEY}</div>;
}

• 后端API路由中使用：

// pages/api/secret.js
export default function handler(req, res) {
  // 仅服务器端可访问，不会暴露到前端
  res.status(200).json({ secret: process.env.PRIVATE_API_KEY });
}

常见问题排查 #

1. 构建报错：删除构建脚本中多余的变量导出语句，恢复默认构建命令
2. 前端变量未生效：确认变量名以NEXT_PUBLIC_开头，保存Amplify配置后重新构建
3. 敏感信息泄露：后端变量禁止添加NEXT_PUBLIC_前缀，禁止勾选「暴露给前端构建」

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