
Next.js 要求客户端可访问的环境变量必须以 NEXT_PUBLIC_ 开头,否则在浏览器端读取时将返回 undefined;这与 Create React App 的 REACT_APP_ 前缀机制不同,需按 Next.js 规范重命名并重启开发服务器。
next.js 要求客户端可访问的环境变量必须以 next_public_ 开头,否则在浏览器端读取时将返回 undefined;这与 create react app 的 react_app_ 前缀机制不同,需按 next.js 规范重命名并重启开发服务器。
在 Next.js 中,环境变量的加载机制与标准 React(如 Create React App)有本质区别:并非所有 .env 变量默认暴露给浏览器端。Next.js 为安全起见,严格区分服务端与客户端环境变量:
- ✅ 客户端可访问变量:必须以
NEXT_PUBLIC_为前缀(例如NEXT_PUBLIC_API_KEY),构建时会被内联到客户端 JavaScript 包中; - ❌ 非前缀变量(如
REACT_APP_API_KEY或API_KEY):仅在 Node.js 服务端(如getServerSideProps、API Routes)可用,在浏览器中始终为undefined。
因此,您当前的 .env 文件需修改为:
NEXT_PUBLIC_API_KEY=myapikey
并在代码中统一使用该名称:
一个基于官方 Mailtrap Node.js SDK 构建的 ASE 技能,用于发送事务邮件并与 Mailtrap 沙盒或生产流程协作。它非常适合需要 API 驱动邮件投递、测试邮箱验证和结构化消息自动化的代理工作流。
// _app.tsx 或任意客户端组件
import { useState, useEffect } from 'react';
export default function MyApp() {
const [apikey, setApikey] = useState<string | undefined>(process.env.NEXT_PUBLIC_API_KEY);
useEffect(() => {
console.log('API Key:', apikey); // ✅ 此时将正确输出 'myapikey'
}, [apikey]);
return <div>My App</div>;
}⚠️ 重要注意事项:
- 修改
.env后必须重启 Next.js 开发服务器(npm run dev→Ctrl+C→npm run dev),因为环境变量在启动时被静态读取; -
NEXT_PUBLIC_前缀不可省略或拼写错误(如NEXT_PUBLIC_APIKEY少下划线将无效); - 敏感密钥(如数据库密码、JWT 秘钥)绝不可加
NEXT_PUBLIC_前缀,应仅用于服务端逻辑; - 推荐在项目根目录创建
.env.local存放本地敏感配置,并将其加入.gitignore,避免误提交。
遵循此规范,即可无缝迁移环境变量逻辑,确保 Next.js 应用安全、稳定地读取前端所需配置。

















