
Next.js 对环境变量命名有严格要求,仅以 NEXT_PUBLIC_ 开头的变量才会在客户端暴露,原 React 的 REACT_APP_ 前缀无效,需重命名并遵循其作用域规则。
next.js 对环境变量命名有严格要求,仅以 `next_public_` 开头的变量才会在客户端暴露,原 react 的 `react_app_` 前缀无效,需重命名并遵循其作用域规则。
在 Next.js 中,环境变量的行为与 Create React App(CRA)有本质区别:Next.js 不自动识别 REACT_APP_ 前缀,也不支持直接在浏览器端访问任意 .env 变量。所有需在客户端(如 _app.js、页面组件或浏览器中)使用的环境变量,必须以 NEXT_PUBLIC_ 为前缀,否则将被编译时忽略,读取结果为 undefined。
✅ 正确做法如下:
-
重命名环境变量
将.env文件中的变量改为 Next.js 兼容格式:NEXT_PUBLIC_API_KEY=myapikey
-
在代码中直接引用(无需
process.env.前缀校验,Next.js 会自动注入)
Mailtrap Node.js SDK 用于事务性和沙盒电子邮件下载一个基于官方 Mailtrap Node.js SDK 构建的 ASE 技能,用于发送事务邮件并与 Mailtrap 沙盒或生产流程协作。它非常适合需要 API 驱动邮件投递、测试邮箱验证和结构化消息自动化的代理工作流。
// _app.tsx 或任意客户端组件 import { useState, useEffect } from 'react'; export default function MyApp({ Component, pageProps }) { const [apikey, setApikey] = useState(process.env.NEXT_PUBLIC_API_KEY); useEffect(() => { console.log('API Key:', apikey); // ✅ 输出 "myapikey" }, []); return <Component {...pageProps} />; }
⚠️ 重要注意事项:
-
NEXT_PUBLIC_前缀是强制要求,不可省略或替换为其他前缀(如NEXT_、REACT_APP_均无效); - 只有带该前缀的变量才会被注入到客户端 JavaScript 中;服务端环境变量(如
DATABASE_URL)无需公开前缀,但不能在浏览器中访问; -
.env文件需位于项目根目录(与next.config.js同级),且需重启开发服务器(npm run dev)才能生效; - Next.js 默认仅加载
.env.local(已忽略.env的 Git 提交风险),建议将敏感配置放在.env.local并添加至.gitignore。
? 小技巧:可通过 console.log(process.env) 在服务端(如 getServerSideProps)查看所有可用变量,但在客户端组件中仅能看到 NEXT_PUBLIC_* 变量。
总结:从 React 迁移至 Next.js 时,环境变量不是“不工作”,而是需要适配其安全模型——显式声明公开意图。一次重命名(REACT_APP_API_KEY → NEXT_PUBLIC_API_KEY),即可彻底解决 undefined 问题。

















