Next.js部署环境变量未生效及敏感PRIVATE_KEY安全使用咨询

1. 部署平台环境变量不生效的原因 #

主要有以下几个常见问题：

• 客户端变量缺少NEXT_PUBLIC_前缀：Next.js默认仅将带NEXT_PUBLIC_前缀的环境变量暴露给客户端代码。你之前的PUBLIC_KEY未加前缀，本地因next.config.js的兜底配置生效，但部署平台无此兜底，导致客户端无法读取变量。
• 部署后未触发重新构建：在Vercel或AWS Amplify添加环境变量后，必须重新部署应用。旧构建包不会自动加载新变量，从而出现变量未定义的情况。
• 平台环境变量配置范围错误：比如在Vercel中仅给Development环境配置了变量，但部署的是Production环境；AWS Amplify也需确保变量配置在对应部署环境中。
• Next.js版本/路由模式差异：若使用App Router，需确保代码正确读取环境变量（服务端组件直接用process.env，客户端组件用process.env.NEXT_PUBLIC_*），部分旧版本Next.js的环境变量加载逻辑存在差异。

2. 安全使用敏感环境变量的方案 #

可以完全避免PRIVATE_KEY泄露，同时让平台环境变量正常工作，具体步骤如下：

步骤1：修正环境变量命名 #

• 客户端所需的公开密钥添加NEXT_PUBLIC_前缀，改为NEXT_PUBLIC_PUBLIC_KEY，确保本地.env和部署平台配置后，客户端能安全读取。
• 服务端用的PRIVATE_KEY保持原命名，无需加前缀，仅在服务端代码中读取。

修改后的本地.env文件：

# .env
NEXT_PUBLIC_PUBLIC_KEY=PUBLIC
PRIVATE_KEY=PRIVATE

步骤2：移除next.config.js中的不安全配置 #

删除next.config.js里的env字段，避免敏感变量被打包到客户端：

// next.config.js
module.exports = {
  // 移除原有的env字段
};

步骤3：在对应代码中正确读取变量 #

• 客户端组件（use client）：直接使用process.env.NEXT_PUBLIC_PUBLIC_KEY，该变量会被安全暴露给客户端：

'use client';

export default function ContactPage() {
  const publicKey = process.env.NEXT_PUBLIC_PUBLIC_KEY;
  // 业务逻辑中使用publicKey
  return <div>联系我们</div>;
}

• 服务端代码（API路由/服务端组件）：直接使用process.env.PRIVATE_KEY，这类代码仅在服务端运行，不会被打包到客户端：

// app/api/contact/route.js (App Router)
export async function POST(request) {
  const privateKey = process.env.PRIVATE_KEY;
  // 使用privateKey处理邮件发送逻辑
  return Response.json({ success: true });
}

步骤4：在部署平台正确配置变量 #

• Vercel：进入项目设置 → Environment Variables，添加NEXT_PUBLIC_PUBLIC_KEY和PRIVATE_KEY，选择对应环境（Production/Preview）后点击"Deploy"重新部署。
• AWS Amplify：进入应用设置 → Environment variables，添加两个变量，触发重新构建部署。

关键注意事项 #

Environment variables specified this way will always be included in the JavaScript bundle. Prefixing the environment variable name with NEXT_PUBLIC_ only has an effect when specifying them through the environment or .env files.
—— Next.js官方文档

绝对不要将敏感变量放入next.config.js的env字段中，无论是否加前缀，都会被打包进客户端代码，造成泄露风险。服务端变量只要不在客户端代码中引用，就不会被暴露。

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