本文深入探讨 Next.
js
应用中环境变量在生产环境失效的常见问题，特别是针对服务器端 API 路由。文章详细阐述了 NEXT_PUBLIC_ 前缀的正确使用场景，指出服务器端秘密值不应使用此前缀，并提供了一种通过 API 路由安全暴露公共环境变量的策略，确保应用在本地和生产环境中均能正确访问所需配置。
Next.js 应用中环境变量的挑战
在开发 next.js 单页应用（spa）时，我们经常需要使用环境变量来存储敏感信息（如 api 密钥、数据库凭证）或配置项。在本地开发环境中，通过 .env 或 .env.local 文件管理这些变量通常运行良好。然而，当应用部署到生产环境时，开发者可能会遇到环境变量无法正确加载，导致功能异常（例如，外部 api 调用失败，报错信息如“the incoming
json
object does not contain a client_email field”）。这通常源于对 next.js 环境变量处理机制的误解，尤其是在服务器端 api 路由中。
理解 Next.js 环境变量的前缀规则
Next.js 对环境变量的处理有明确的规则，主要通过 NEXT_PUBLIC_ 前缀来区分：
NEXT_PUBLIC_ 前缀变量：
带有 NEXT_PUBLIC_ 前缀的环境变量会被注入到客户端 JavaScript bundle 中。这意味着这些变量可以在
浏览器
端代码中直接访问，但它们是公开的，
不应包含任何敏感信息
。
无前缀变量：
没有 NEXT_PUBLIC_ 前缀的环境变量仅在服务器端可用。这包括 Next.js 的 Node.js 服务器环境、API 路由（pages/api 或 app/api）以及 getServerSideProps、getStaticProps 等数据获取函数。这些变量是安全的，可以存储敏感信息。
核心问题：
许多开发者误以为所有环境变量都需要 NEXT_PUBLIC_ 前缀才能在生产环境中被识别，或是在服务器端 API 路由中错误地使用了带有 NEXT_PUBLIC_ 前缀的敏感变量。
解决方案一：纠正服务器端秘密值的命名
对于需要在服务器端（例如 Next.js API 路由）使用的秘密值，如 Google API 的 client_email 和 private_key，它们
不应该
带有 NEXT_PUBLIC_ 前缀。因为 API 路由运行在服务器端，这些变量应该被视为服务器端变量。
错误的配置示例（导致生产环境失效）：
正确的配置示例（适用于服务器端 API 路由）：
修改 submit.js API 路由文件：
在 API 路由中，直接通过 process.env 访问这些无前缀的变量：
通过移除 NEXT_PUBLIC_ 前缀，这些变量将只在服务器端可用，从而解决了“client_email field missing”的错误，并增强了安全性。
解决方案二：通过 API 路由安全地暴露公共环境变量（如果需要）
虽然服务器端秘密值不应带有 NEXT_PUBLIC_ 前缀，但有时客户端确实需要访问一些公共的配置变量，例如 Google Tag Manager (GTM) ID，这些变量理应带有 NEXT_PUBLIC_ 前缀。如果这些 NEXT_PUBLIC_ 变量在生产环境中仍无法加载，或者出于某种原因需要在运行时动态获取，可以通过创建一个专门的 API 路由来暴露它们。
Comet AI 浏览器
下载 Comet AI 浏览器，体验由 Perplexity AI 驱动的革命性上网方式。内置 AI 助手可实时总结网页、跨标签页对比信息、自动执行任务。告别繁琐操作，让 AI 成为你的浏览副驾，大幅提升研究与工作效率。支持 Windows、macOS、Android 和 iOS。
下载
创建 pages/api/env.js 文件：
客户端如何访问这些变量：
在客户端组件中，可以通过 fetch 请求调用这个 API 路由来获取公共环境变量：
这种方法提供了一个健壮的机制，确保客户端能够访问所需的公共配置，即使在构建时注入的环境变量出现问题，或者需要动态更新这些变量时。
部署环境中的环境变量管理
无论是在 Docker、AWS、Vercel 还是其他云平台上部署 Next.js 应用，生产环境中的环境变量都应通过平台提供的安全机制进行配置，而不是直接提交到代码仓库或依赖 .env.local 文件。
Vercel：
在项目设置中配置环境变量。
AWS ECS/Lambda：
通过任务定义或 Lambda 函数配置环境变量。
Docker：
使用 Docker Compose 的 environment 字段或
docker
run -e 命令注入环境变量。
确保这些环境变量在部署时被正确注入到 Next.js 运行时环境中至关重要。
总结与最佳实践
区分服务器端与客户端变量：
服务器端秘密值（如 API 密钥）：
不要
使用 NEXT_PUBLIC_ 前缀，仅在服务器端（API 路由、getServerSideProps 等）访问。
客户端公共值（如 GTM ID）：
使用 NEXT_PUBLIC_ 前缀，它们会被打包到客户端代码中。
安全性优先：
永远不要将敏感信息（如私钥）直接暴露给客户端。
生产环境配置：
避免依赖 .env.local 文件在生产环境工作。使用部署平台提供的环境变量管理工具。
动态获取公共变量：
如果 NEXT_PUBLIC_ 变量在客户端无法正常加载，或者需要更灵活的配置管理，可以考虑通过 API 路由动态获取。
遵循这些原则，可以有效避免 Next.js 应用在生产环境中因环境变量配置不当而导致的问题，确保应用稳定、安全地运行。
# .env 或生产环境配置中
NEXT_PUBLIC_GOOGLE_CLIENT_EMAIL=your-client-email@project.iam.gserviceaccount.com
NEXT_PUBLIC_GOOGLE_PRIVATE_KEY=-----BEGIN PRIVATE KEY-----
...
-----END PRIVATE KEY-----
NEXT_PUBLIC_GOOGLE_SHEET_ID=your-sheet-id# .env 或生产环境配置中
GOOGLE_CLIENT_EMAIL=your-client-email@project.iam.gserviceaccount.com
GOOGLE_PRIVATE_KEY=-----BEGIN PRIVATE KEY-----
...
-----END PRIVATE KEY-----
GOOGLE_SHEET_ID=your-sheet-idimport { google } from 'googleapis';
// 移除 dotenv-flow，在 Next.js 环境中通常不需要手动配置
// require('dotenv-flow').config()
export default async function handler(req, res) {
if (req.method !== 'POST') {
return res.status(405).send('Only POST requests are allowed!');
}
const body = req.body;
try {
const auth = new google.auth.GoogleAuth({
credentials: {
// 直接访问无 NEXT_PUBLIC_ 前缀的变量
client_email: process.env.GOOGLE_CLIENT_EMAIL,
private_key: process.env.GOOGLE_PRIVATE_KEY?.replace(/\n/g, '
'),
},
scopes: [
'https://www.googleapis.com/auth/drive',
'https://www.googleapis.com/auth/drive.file',
'https://www.googleapis.com/auth/spreadsheets',
],
});
const sheets = google.sheets({
auth,
version: 'v4',
});
const submittedAt = new Date().toUTCString();
const response = await sheets.spreadsheets.values.append({
spreadsheetId: process.env.GOOGLE_SHEET_ID, // 同样访问无 NEXT_PUBLIC_ 前缀的变量
range: 'A1:F1',
valueInputOption: 'USER_ENTERED',
requestBody: {
values: [
[
body.name,
body.company,
body.product,
body.email,
body.phone,
submittedAt,
],
],
},
});
return res.status(201).json({
data: response.data,
});
} catch (error) {
console.error('Google Sheets API error:', error); // 使用 console.error 记录错误
// 错误处理时，避免直接暴露敏感信息，但可以记录错误详情
return res.status(error.code || 500).send({ message: error.message || 'An unexpected error occurred.' });
}
}// pages/api/env.js
export default function handler(req, res) {
// 过滤出所有以 'NEXT_PUBLIC_' 开头的环境变量
const publicEnv = Object.keys(process.env)
.filter((key) => key.startsWith('NEXT_PUBLIC_'))
.reduce((acc, key) => {
acc[key] = process.env[key];
return acc;
}, {});
// 返回 JSON 格式的公共环境变量
res.status(200).json(publicEnv);
}// 例如，在某个 React 组件中
import React, { useEffect, useState } from 'react';
function MyComponent() {
const [envVars, setEnvVars] = useState({});
useEffect(() => {
async function fetchEnvVars() {
try {
const response = await fetch('/api/env');
const data = await response.json();
setEnvVars(data);
} catch (error) {
console.error('Failed to fetch public environment variables:', error);
}
}
fetchEnvVars();
}, []);
// 现在可以在组件中使用 envVars.NEXT_PUBLIC_GTM_ID 等变量
return (
GTM ID: {envVars.NEXT_PUBLIC_GTM_ID || 'Loading...'}
{/* ... 其他使用公共变量的代码 */}
);
}
export default MyComponent;