
在 next.js 应用开发中,环境变量是管理配置信息,尤其是敏感凭证的关键。next.js 对环境变量的处理方式有所不同,主要取决于它们是否带有 next_public_ 前缀以及它们是在服务器端还是客户端被访问。
许多开发者在本地开发时环境变量工作正常,但在部署到生产环境后却遇到问题,例如出现 500 错误或关键凭证缺失。这通常源于对 NEXT_PUBLIC_ 前缀的误用以及对 Next.js 服务器端/客户端上下文的混淆。
例如,一个常见的场景是,将 Google Sheet API 的敏感凭证(如 client_email 和 private_key)存储在 .env.local 文件中,并尝试在 Next.js 的 API 路由(这是一个服务器端环境)中通过 process.env.NEXT_PUBLIC_GOOGLE_CLIENT_EMAIL 访问。尽管在本地可能有效,但在生产环境中,这会导致凭证无法正确加载,进而引发认证失败。错误信息如 Error: The incoming JSON object does not contain a client_email field 明确指出 client_email 字段为空或未定义。
对于仅在服务器端(例如 Next.js API 路由)使用的敏感环境变量,如 Google API 凭证,绝不能使用 NEXT_PUBLIC_ 前缀。NEXT_PUBLIC_ 旨在将变量暴露给客户端,而服务器端代码可以访问所有未加前缀的环境变量。
错误的配置示例(在服务器端使用):
NEXT_PUBLIC_GOOGLE_CLIENT_EMAIL=your_client_email NEXT_PUBLIC_GOOGLE_PRIVATE_KEY=your_private_key NEXT_PUBLIC_GOOGLE_SHEET_ID=your_sheet_id
正确的配置示例(在服务器端使用):
将 .env 或 .env.local(或通过部署平台注入)中的变量名修改为不带 NEXT_PUBLIC_ 前缀:
GOOGLE_CLIENT_EMAIL=your_client_email GOOGLE_PRIVATE_KEY=your_private_key GOOGLE_SHEET_ID=your_sheet_id
相应地,在你的 Next.js API 路由(例如 submit.js)中,访问这些变量时也应移除 NEXT_PUBLIC_ 前缀:
// pages/api/submit.js
import { google } from 'googleapis';
// 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({
// 移除 NEXT_PUBLIC_ 前缀
spreadsheetId: process.env.GOOGLE_SHEET_ID,
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('Error submitting form:', error); // 使用 console.error 记录错误
// 确保错误处理中不暴露敏感信息
return res.status(error.code || 500).send({ message: error.message || 'An unexpected error occurred.' });
}
}通过移除 NEXT_PUBLIC_ 前缀,这些敏感变量将仅在服务器端可用,从而解决了生产环境中凭证无法加载的问题。
有时,即使是带有 NEXT_PUBLIC_ 前缀的公共环境变量,在某些复杂的部署环境或自定义构建流程中,也可能无法在客户端正确加载。为了确保这些公共变量在客户端可用,并且避免直接在构建时硬编码,可以采用通过 Next.js API 路由动态获取并暴露的方式。
这种方法尤其适用于那些需要在运行时动态获取,或者在客户端 JavaScript 包中不希望直接包含所有 NEXT_PUBLIC_ 变量的场景。
步骤 1:创建一个 API 路由来暴露公共环境变量
在 pages/api 目录下创建一个文件,例如 pages/api/env.js:
// 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);
}这个 API 路由会遍历 process.env 对象,筛选出所有以 NEXT_PUBLIC_ 开头的变量,并将它们作为 JSON 对象返回。
步骤 2:在客户端组件中调用 API 路由获取环境变量
在你的 React 组件或任何客户端代码中,你可以通过 fetch 请求调用这个 API 路由来获取公共环境变量:
// components/MyClientComponent.js
import React, { useEffect, useState } from 'react';
function MyClientComponent() {
const [envVars, setEnvVars] = useState({});
const [loading, setLoading] = useState(true);
const [error, setError] = useState(null);
useEffect(() => {
async function fetchPublicEnv() {
try {
const response = await fetch('/api/env'); // 调用上面创建的 API 路由
if (!response.ok) {
throw new Error(`HTTP error! status: ${response.status}`);
}
const data = await response.json();
setEnvVars(data);
} catch (e) {
setError(e);
} finally {
setLoading(false);
}
}
fetchPublicEnv();
}, []);
if (loading) return <div>Loading public environment variables...</div>;
if (error) return <div>Error: {error.message}</div>;
return (
<div>
<h2>Public Environment Variables:</h2>
<ul>
{Object.entries(envVars).map(([key, value]) => (
<li key={key}>
<strong>{key}:</strong> {value}
</li>
))}
</ul>
{/* 示例:使用 GTM ID */}
{envVars.NEXT_PUBLIC_GTM_ID && (
<p>Google Tag Manager ID: {envVars.NEXT_PUBLIC_GTM_ID}</p>
)}
</div>
);
}
export default MyClientComponent;这种方法提供了一个集中且受控的方式来将公共环境变量暴露给客户端,尤其是在 NEXT_PUBLIC_ 变量在客户端无法直接访问时,或者需要更细粒度的控制时。
Next.js 环境变量的管理需要清晰地理解服务器端和客户端的上下文,以及 NEXT_PUBLIC_ 前缀的含义。对于服务器端使用的敏感凭证,应避免使用 NEXT_PUBLIC_ 前缀。对于需要在客户端使用的公共环境变量,若直接访问存在问题,通过专门的 API 路由进行安全地获取和暴露是一种稳健的解决方案。遵循这些最佳实践,可以有效避免生产环境中环境变量加载失败的问题,确保应用的安全性和稳定性。
以上就是Next.js 环境变量在生产环境中加载失败的排查与解决方案的详细内容,更多请关注php中文网其它相关文章!
每个人都需要一台速度更快、更稳定的 PC。随着时间的推移,垃圾文件、旧注册表数据和不必要的后台进程会占用资源并降低性能。幸运的是,许多工具可以让 Windows 保持平稳运行。
Copyright 2014-2025 https://www.php.cn/ All Rights Reserved | php.cn | 湘ICP备2023035733号