我们平时写 Next.js 应用时环境变量这件事总在最后关头跳出来给个惊喜。明明本地跑得好好的一到部署就连环报错翻遍日志才发现是变量没传进去。实际上环境变量并不只是“往”.env 文件里塞几个键值对那么简单它背后牵扯到前端与后端的隔离、构建时机、安全边界这些核心问题。这篇文章会把 Next.js 中环境变量的完整逻辑拆开讲清楚从原理到实操都过一遍。1. 环境变量在 Next.js 中的两种截然不同的命运1.1 NEXT_PUBLIC 前缀决定了变量是“公开”还是“私有”很多初学者会纳闷明明都是写在同一个.env 文件里的变量为什么有些在浏览器里能直接用有些却怎么都拿不到。这个问题的答案就在前缀上。在 Next.js 中以 NEXT_PUBLIC_ 开头声明的变量会被编译进客户端的 JavaScript 包。举个例子NEXT_PUBLIC_API_URLhttps://api.example.com SECRET_API_KEYsk_123456NEXT_PUBLIC_API_URL 可以被页面组件中的process.env.NEXT_PUBLIC_API_URL直接读取因为构建时它会被替换成字符串字面量放进产物里。而 SECRET_API_KEY 只存在于服务器端环境中如果你试图在客户端组件里访问它得到的会是 undefined没有任何报错提示排查起来特别隐蔽。这里有一个很关键的理解点客户端变量本质上是“公开”的。不管你是否愿意凡是 NEXT_PUBLIC_ 开头的变量都会被打包进浏览器可访问的代码里意味着用户可以在浏览器开发者工具的 Sources 面板中搜索到它的值。所以 Cookie、密钥、数据库连接串这类敏感信息绝对不能挂在 NEXT_PUBLIC_ 前缀下。我在实际项目里见过有人把数据库密码写成 NEXT_PUBLIC_DB_PASSWORD这等于把密码明晃晃地挂在了网站上。1.2 构建时注入与运行时读取的差异Next.js 处理环境变量的时机分为构建期和运行期这与参与渲染的组件类型密切相关。服务器端组件RSC、路由处理程序Route Handlers和服务器端 API 中访问的环境变量是在服务端运行时读取的。也就是说这些变量只要在部署环境比如 Docker 容器、云平台的控制台中正确配置构建之后再修改也依然能生效因为它们是动态从系统环境里读取的。但客户端变量不是这样。NEXT_PUBLIC_ 前缀的变量会在执行next build时被静态替换成它们当时的值。代码里的process.env.NEXT_PUBLIC_SITE_NAME在构建阶段就会变成My Blog这样的一个字符串常量随后被打包进 JS 文件。如果你在构建后的机器上修改了环境变量重新部署但未重新构建前端代码里拿到的仍然是旧值。理解这两者的差异能省去很多排查时间。我第一次遇到这个问题时本地测试一切正常部署到服务器后发现网站标题没有变但接口地址的请求是新的。折腾了半天才意识到标题用的是 NEXT_PUBLIC_在构建时就被定死了而我部署时没有重新执行 next build。1.3 为什么 Next.js 要这样区分这个设计表面上只是前缀的区别本质上是在约束数据边界。客户端代码天然是透明的任何人都能读到你打包后的脚本。如果所有环境变量都无差别地打进客户端代码那些服务器端密钥就完全无法保密了。反过来如果所有变量都只在服务端存在让浏览器调用接口时就没有办法动态决定请求地址。所以 Next.js 给了一条简单的规则需要暴露给浏览器的明确加上 NEXT_PUBLIC_不需要暴露的留在服务器端。能用这个规则快速判断哪些变量该放在哪个环境项目出问题时的排查范围也会小很多。2. 配置文件的分工与加载优先级2.1 五种 .env 文件分别用在什么场景Next.js 默认会读取项目根目录下的 .env 文件除此之外针对不同场景还有几个衍生文件。我整理了一个实际项目中比较常见的分工文件用途典型场景.env所有环境共享的默认配置公共服务名、非敏感的项目元信息.env.development仅开发环境下使用执行 next dev 时加载本地调试用的模拟服务地址.env.production仅生产构建环境下使用执行 next start 或 next build 时加载生产接口地址、分析服务 ID.env.local本地覆盖优先级最高不会被 git 提交个人开发机专属的令牌、密钥.env.production.local生产环境本地覆盖文件同样不会提交部署到服务器后手动注入的本地变量这个设计参考了 Create React App 等成熟工具的惯例但需要注意一点.env.local 在测试环境下不会被加载Next.js 会在运行next test时默认忽略它这是官方文档里专门提到过的坑。如果在跑测试时发现某些变量取不到先看看是不是写在了 .env.local 里。2.2 环境变量加载的优先级排序当同一个变量名在多个文件中被定义时Next.js 会根据一个明确的优先级顺序取值。从高到低依次是操作系统环境变量process.env 中已存在比如 CI 平台注入的变量.env.{environment}.local.env.local测试环境下不会加载.env.{environment}.env这里的逻辑很直观越具体的配置越优先。例如在开发时开发环境专属的 .env.development.local 会覆盖 .env.development而 .env.development 又会覆盖 .env。我在一个多环境项目里这样组织过基础公共配置放到 .env测试环境写 .env.test生产环境写 .env.production而本机独有的调试开关就放 .env.local。这样团队成员克隆仓库后直接 npm install 就能跑每个人本地的小偏好互不干扰代码也不会被无意义的个人配置撑乱。需要注意不要在一个文件里写大量注释来说明变量含义更合适的做法是在 .env.example 里放一个“样本文件”只写键名和占位符并提交到仓库。这样新人来了看着示例就知道要配哪些变量真实值通过本地或部署平台去注入而不是明文入库。3. 从零到一配置环境变量的完整演练3.1 创建一个可复现的示例项目我用一个简单的信息展示页面来示范整个流程你跟着操作一遍基本就能掌握。npx create-next-applatest env-demo --ts --app cd env-demo先创建两个文件分别代表不同用途的变量# .env SITE_NAME默认站名 NEXT_PUBLIC_SITE_NAME默认站名 API_BASE_URLhttp://localhost:8080# .env.local SITE_NAME本地覆盖站名 NEXT_PUBLIC_SITE_NAME本地覆盖站名 API_BASE_URLhttp://127.0.0.1:3001再新建一个 API 路由来验证服务端读取情况// app/api/info/route.ts import { NextResponse } from next/server; export async function GET() { return NextResponse.json({ siteName: process.env.SITE_NAME, apiBase: process.env.API_BASE_URL, }); }同时改造首页显示客户端能拿到什么// app/page.tsx export default function Home() { return ( main p客户端站名{process.env.NEXT_PUBLIC_SITE_NAME}/p p客户端 API 地址{process.env.API_BASE_URL || 访问不到}/p /main ); }3.2 在开发模式下观察变量的实际取值执行npm run dev打开浏览器看页面客户端站名显示“本地覆盖站名”客户端 API 地址显示“访问不到”。这是因为 API_BASE_URL 没有 NEXT_PUBLIC_ 前缀在客户端组件中被视为 undefined所以走了备用文案。再访问/api/info返回的是siteName: 本地覆盖站名apiBase: http://127.0.0.1:3001。这说明服务端在开发时读取到了 .env.local 里优先级更高的配置。这个对照结果很重要同一个变量名在前端和后端获取到的值可能完全不一样它们不是一个全局共享的字典而是根据当前运行环境各取各的一份。3.3 切换到生产构建验证构建期注入停止开发服务器执行npm run build npm run start再次访问页面客户端站名依然显示“本地覆盖站名”因为 .env.local 在生产构建时也生效。如果你把 .env.local 的 NEXT_PUBLIC_SITE_NAME 改成“生产站名”重新执行 build前端的字符串才会变成新值。试着在运行npm run start之前在终端里临时设置一个环境变量再启动SITE_NAME命令行站名 npm run start这时访问 /api/info返回的是“命令行站名”。这个行为说明服务端读取环境变量是动态的后端每次请求时都会重新读取进程环境而前端已经在 build 阶段被定死了。记住这个特性以后你在部署时就能理解为什么修改服务器上的 NEXT_PUBLIC_ 变量不重新构建没有效果了。这也是很多云平台要求你改完环境变量后必须触发一次新的构建的原因。4. 实际开发中最容易踩的五个坑4.1 在客户端组件里读取非 NEXT_PUBLIC 变量得到 undefined这个问题高频出现且难以排查。页面不报错控制台也不报错只有渲染区域少了一块内容。以我上面那个例子举例process.env.API_BASE_URL在客户端组件里永远都是 undefined想要它生效要么给变量加上 NEXT_PUBLIC_ 前缀要么换个思路通过 API 转发请求让浏览器访问同源接口由服务端去调用真正的上游地址。要注意千万不要为了让客户端能拿到密钥就大量使用 NEXT_PUBLIC_ 前缀。正确的思路是浏览器需要什么就只暴露什么绝不额外多给。4.2 .env.local 被提交到了代码仓库.env.local 本来是用来防止敏感配置进仓库的但如果你在 .gitignore 里没有正确忽略这个文件或者为了省事直接使用 git add -f 强制添加过这些密钥就会随着仓库泄露。一个合理的做法是在仓库初始化时就把 .env* 规则写好只保留 .env.example 和 .env.production如果里面全是非敏感值。我见到过一个项目团队把 .env.local 提交到了 GitHub里面包含第三方服务的密钥。第二天就收到了陌生人的邮件提醒说你的密钥已经泄露。从那时起我就养成了一个习惯每次提交前先git status检查新增文件凡是带真实密钥的配置文件一律不碰。4.3 生产构建后修改了 NEXT_PUBLIC_ 变量但没重新构建我前文提到过前端变量是构建时替换的。不少同学在服务器上直接 edit .env.production然后执行 next start结果发现页面上的接口地址没有任何变化。这个行为让很多人误以为是配置没生效但真正的原因是构建产物里的字符串已经写死了。解决办法很简单只要修改了 NEXT_PUBLIC_ 开头的变量必须重新执行npm run build。如果你使用 Docker 部署注意确保 Dockerfile 里构建阶段的 ENV 参数也同步更新了。4.4 在 package.json 的 scripts 里内联变量却没有跨平台兼容有些开发者会在启动命令里直接写{ scripts: { dev: NODE_ENVdevelopment next dev } }这个在 Linux 和 macOS 上没问题但 Windows 的 cmd 和 PowerShell 并不支持这种方式。常见的做法是使用cross-env这个工具来统一处理。虽然这与 .env 文件没有那么直接的关系但团队协作时这是很容易翻车的环境变量坑。4.5 测试环境加载不到 .env.local 里的内容前面提过Next.js 在测试环境下会忽略 .env.local这是有意为之防止个人配置污染 CI 测试。如果你在跑 Jest 或 Playwright 时需要某份测试数据恰好放在 .env.local 里要么把变量迁移到 .env.test 中要么在测试的命令行里注入。我建议统一使用 .env.test 来管理测试专属的变量尤其是接口 mock 地址和测试账号标识。还有一个容易忽略的点当你使用某些测试框架时它们自己会设置 NODE_ENVtest而 Next.js 对这个环境特别处理。测试时不要依赖“本地能跑所以测试也能跑”的经验先设计好测试配置的分层策略。5. 环境变量在不同部署场景中的配置思路5.1 本地开发、Docker 与云平台的区别本地开发环境最宽松.env.local 随便写改完直接重启 dev server 就生效。Docker 部署时环境变量通常通过 Dockerfile 的 ENV 指令或 docker run -e 参数注入。云平台则一般有专门的变量配置面板比如 Vercel、Netlify 的 Environment Variables 区域。关键是分清哪些变量在构建阶段使用哪些在运行阶段使用。如果一个变量只被服务端代码读取运行阶段注入就够了。如果一个变量被 NEXT_PUBLIC_ 使用必须在构建阶段就存在于环境中。很多云平台区分了 Build-time 和 Runtime 两套变量设置不要让它们在概念上混淆。5.2 在 CI/CD 流程中注入环境变量的推荐姿势CI 流程中一道典型环节是“安装依赖 → 构建 → 部署”。构建前需要保证所有 NEXT_PUBLIC_ 变量已经注入。以 GitHub Actions 为例- name: Build env: NEXT_PUBLIC_SITE_NAME: ${{ secrets.NEXT_PUBLIC_SITE_NAME }} run: npm run build如果不把变量传进 env构建时就看不到这些值产物里的对应字符串就会变成 undefined。这部分经验来自几次流水线的修复经历每次都是构建日志里看不到变量名后来通过增加一个临时排查命令才定位到问题。5.3 敏感变量的加密与权限管理即使环境变量放在部署平台的后台一旦团队人多谁都能看到秘钥本身也是一个风险。一种做法是只在 CI 配置中引用 secret日常开发则使用本地的 .env.local并且这个文件永远不离开个人电脑。如果你更倾向于中心化还可以用 Doppler、aws secrets manager 或 HashiCorp Vault 这类工具通过 SDK 在运行时拉取密钥不过这会引入额外的依赖和网络延迟适合企业级项目普通项目里用平台自带的 secret 功能就足够了。6. 提升环境变量使用体验的四个技巧6.1 用 .env.example 构建团队协作的“配置文档”把项目中需要的所有变量、含义、是否为 NEXT_PUBLIC_、是否必填、示例值整理到 .env.example 中。这一步能大幅降低新成员的上手成本。我通常还会在注释里标注该变量在哪个环境里会被覆盖以及对应的默认值是什么。一个常规的 .env.example# 站点名称展示在页面页脚客户端可读取 NEXT_PUBLIC_SITE_NAMEMy Site # 内部 API 地址仅服务端可读取 API_BASE_URLhttp://localhost:3000 # 后台管理端地址仅用于管理后台页面 ADMIN_URLhttps://admin.example.com这份文件要保持简洁尽量不给真实值避免无意泄露。6.2 通过“一个变量多处生效”来验证前缀规则我在给团队讲环境变量时喜欢设计一个练习在 .env.local 中设置三组变量一组只有 NEXT_PUBLIC_一组是普通命名一组是普通命名但在客户端组件里访问。然后分别用两个页面去展示开发者很快就能自己总结出规则。这种体验式学习比死记文档更能帮助记忆。6.3 使用调试中间件打印环境变量如果要在复杂项目中核查哪些环境变量可用可以临时在 API 路由里输出变量名清单但只在开发环境开启。这里有一个安全提示生产环境不要输出任何环境变量名更不要输出值。// app/api/debug/env/route.ts import { NextResponse } from next/server; export async function GET() { if (process.env.NODE_ENV ! development) { return NextResponse.json({ error: not allowed }, { status: 403 }); } return NextResponse.json({ publicSiteName: process.env.NEXT_PUBLIC_SITE_NAME, serverOnly: process.env.SITE_NAME, }); }这种临时接口在排查部署环境时可以帮助你快速确认变量是否真的被注入定位是配置没写对还是平台没配好。6.4 统一管理非 NEXT_PUBLIC_ 的运行时配置有些项目为了避免重复构建把一些非敏感的站点配置做成运行时从数据库或配置中心拉取。这样改配置不用重新部署但要注意带来新的一致性问题配置变了本地缓存如何失效。个人经验是结合 Next.js 的 fetch 选项对配置接口设置合理的 revalidate 时间既避免每次请求都查数据库又能保证配置更新的时效性。7. 一个综合案例多环境多区域的站群配置假设你有一个站群项目需要按国家和区域展示不同的支付方式、语言和客服联系方式。一种方案是使用一组 NEXT_PUBLIC_ 变量配合服务端变量联合控制NEXT_PUBLIC_SITE_REGION 表示站点区域代码例如 us / eu / apacNEXT_PUBLIC_PAYMENT_METHOD 表示支付方式例如 stripe / alipaySERVER_CURRENCY_CONFIG 表示服务端货币换算配置仅内部接口使用在 .env.us.production 中配置美区的站点变量在 .env.eu.production 中配置欧区的站点变量。构建时按区域加载对应的 .env 文件。这样你只需要维护一套代码库通过注入不同环境变量就能产出多个区域的站点同时避免把区域专属的汇率逻辑暴露到客户端。实际执行时先为每个区域准备一份环境文件然后在 CI 中对每个区域分别执行一次构建最后部署到各自区域的服务集群。这套方案不需要改代码只需要在环境变量的组织和管理上做好分层运行起来非常清晰。我踩过一个坑一开始把区域配置全写在同一个 .env.production 里想通过运行时切换区域结果每次切换都要发版。后来改用分文件构建的方式改动量不大但灵活性提升很多。这个话题展开来看环境变量表面上只是配置管理的一小环实际上直接影响了项目的安全性、部署流程的复杂度、团队协作的顺畅程度。花点时间把前缀规则、加载优先级、构建时机的原理理清楚后面少掉的坑远比你花掉的时间值。