1. 为什么环境变量是Next.js项目里最容易翻车的环节先讲个我自己的真实经历。去年维护一个中大型电商后台项目代码里到处是process.env.API_BASE_URL本地跑得好好的测试环境也正常结果一上生产环境所有接口请求全部指向了localhost。排查了整整一个下午最后发现是环境变量文件被提交到了代码仓库生产服务器上压根没有.env.production这个文件而代码里又写了一个|| http://localhost:3000的兜底逻辑。这个坑相信不少人都踩过。Next.js 作为目前最主流的 React 全栈框架之一它的环境变量体系看似简单——不就是几个.env文件吗——但实际用起来涉及构建时注入、运行时读取、服务端与客户端隔离、缓存失效机制等一系列问题。任何一个环节没搞明白轻则功能异常重则敏感信息泄露。这篇文章我打算把自己在多个 Next.js 项目里趟过的坑、验证过的方案、总结出的最佳实践一次性讲清楚。不管你是刚接触 Next.js 的新手还是已经用它做过几个项目的开发者这篇文章应该都能帮你少走不少弯路。我会重点覆盖环境变量的加载规则、.env文件优先级、服务端与客户端变量的区分、运行时动态读取、打包优化、安全防护、以及 CI/CD 中的配置策略。2. Next.js 环境变量的加载规则与文件优先级2.1 系统自带的支持.env 家族的成员们Next.js 从 9.4 版本开始内置了环境变量支持不需要额外安装dotenv之类的库。它在启动时会自动读取项目根目录下的几个文件.env所有环境通用的基础配置.env.development仅在next dev时加载.env.production仅在next build或next start时加载.env.local本地开发专属配置不会被next build加载.env.development.local开发环境本地覆盖.env.production.local生产环境本地覆盖这一套文件体系的设计逻辑其实很清晰把所有环境共享、按环境区分、仅限本地三个维度分开管理。但很多人忽略了一个关键点——优先级顺序。代码中读取环境变量时如果同一个变量在多个文件中都有定义实际生效的是按以下优先级从高到低真实的环境变量在 shell 或 CI 中通过export/ 环境配置设置的.env.production.local/.env.development.local.env.local.env.production/.env.development.env也就是说优先级顺序是process.env 中已经存在的值 带 .local 后缀的文件 不带后缀的按环境区分的文件 基础 .env。这点非常重要因为很多人以为.env.production是最权威的实际上它只是比.env高一级真正最高优先级是系统环境变量。我用一张表格总结一下不同命令对应加载的文件执行命令加载的文件next dev.env.development.local、.env.local、.env.development、.envnext build.env.production.local、.env.production、.envnext start.env.production.local、.env.production、.envnext dev同时存在 .env.local 和 .env.development先读.env.development.local再读.env.local最后读.env.development这里有个极其容易踩坑的点.env.local在next build时不会被加载。我见过不少团队把生产环境的数据库连接串放在.env.local里本地开发时一切正常构建镜像时却发现变量全部丢失因为 Docker 构建阶段执行的next build压根不看这个文件。正确做法是生产环境必须通过 CI/CD 平台的变量注入机制或 Docker 镜像的ENV指令来提供变量而不是依赖文件。2.2 NODE_ENV 的特殊行为Next.js 本身会自动设置NODE_ENV你手动在.env文件里写NODE_ENVproduction是无效的它会被 Next.js 内部覆盖。这个变量决定了使用哪一套.env.*文件所以千万别试图手动改它。还有个我后来才注意到的小细节如果你同时使用了.env和.env.local且两个文件里都定义了同一个变量.env.local会覆盖.env。这本来是设计给本地覆盖用的但如果你不小心把.env.local提交到了代码仓库那么所有部署环境的变量都会被你的本地值覆盖——这个问题我在后面安全部分还会专门展开讲。2.3 环境变量的缓存机制改了不生效怎么办这是 Next.js 环境变量体系里最容易让人抓狂的问题。你明明改了.env.local里的值重启 dev server 之后发现页面里打印的还是旧值。原因在于Next.js 在构建时会把引用环境变量的代码直接进行文本替换而不是运行时去读取process.env。举个例子你在代码里写了const apiUrl process.env.NEXT_PUBLIC_API_URLnext build时如果NEXT_PUBLIC_API_URLhttps://api.example.com那么编译产物里这一行就会直接变成const apiUrl https://api.example.com。这意味着什么意味着改了变量后必须重启dev server 或重新执行next build如果是生产环境部署的改环境变量后必须重新构建不能只重启 Node.js 进程某些场景下即使重启了 dev server 也没生效可能是因为.next缓存目录需要手动删除node_modules/.next或者.next目录后再启动我自己更倾向于用rm -rf .next next dev的方式来彻底清缓存。虽然有点粗暴但确实能解决绝大多数改了不生效的问题。3. 服务端组件与客户端组件环境变量的隔离红线3.1 NEXT_PUBLIC_ 前缀到底意味着什么Next.js 有一套明确的安全机制默认情况下环境变量只在服务端可用Node.js 运行时。如果你在客户端组件里直接写process.env.SECRET_KEY拿到的是一个空值而且如果代码中引用了不存在的变量Next.js 在构建时会直接报错提示该变量未定义。要让某个变量在浏览器端也可用必须给变量名加上NEXT_PUBLIC_前缀。带这个前缀的变量会在构建时被内联到客户端 JavaScript 包中。这个设计的用意非常明显防止把服务端密钥暴露给浏览器用户。因为NEXT_PUBLIC_前缀意味着我明确知道这个信息可以公开会随着打包后的 JS 文件一起下发到每个用户的浏览器里。但很多初学者会犯一个错误把真实的 API 密钥、数据库密码等敏感信息加上NEXT_PUBLIC_前缀以为只是让前端也能访问而已。结果就是密钥直接暴露在前端源码里任何人打开浏览器开发者工具就能看到。提示凡是以NEXT_PUBLIC_开头的变量内容都会被发送到客户端。请用这个前缀时反问自己一句——这个信息能公开给全世界人看吗3.2 App Router 下的服务端组件环境变量Next.js 13 之后推出的 App Router 引入了服务端组件的概念默认情况下组件都是服务端组件。在服务端组件里读取环境变量不需要NEXT_PUBLIC_前缀直接process.env.DATABASE_URL即可正常访问。这在实践中意味着一个很关键的架构优化机会凡是需要在客户端展示的数据请求、需要密钥鉴权的第三方 API 调用都应该尽量放在服务端组件或 Server Actions 里执行这样你只需要在服务端持有密钥客户端拿到的只是处理好的数据结果。比如一个典型的场景从数据库读取商品列表。如果放在服务端组件里做数据库连接串只需要存在于服务器环境浏览器端永远接触不到。反之如果让客户端组件直接请求数据库接口就不得不把连接信息暴露给前端——这在架构上就是错误的。我维护过一个项目最初开发时把所有数据请求都放在客户端组件里API Key 用NEXT_PUBLIC_暴露。后来重构为服务端组件后不仅 API Key 从客户端代码里消失了整个页面首屏加载速度也提升了不少因为数据请求从客户端异步请求变成了服务端直接渲染。3.3 在客户端组件中安全地使用服务端变量那么问题来了客户端组件确实需要获取某个服务端才知道的变量怎么办比如用户登录后需要拿到用户 ID 去拼接头像 URL。正确做法是在服务端组件中读取变量然后通过 props 传给客户端组件。或者用 Next.js 提供的cookies()、headers()这些函数在服务端获取上下文信息通过 Server Actions 或 Route Handlers 提供给客户端。具体示例如下// app/layout.tsx - 服务端组件 import { ClientHeader } from ./ClientHeader; export default async function Layout({ children }) { const appName process.env.APP_NAME; // 服务端可访问 const user await getCurrentUser(); // 服务端获取用户信息 return ( html body ClientHeader appName{appName} user{user} / {children} /body /html ); }// ClientHeader.tsx - 客户端组件 use client; export function ClientHeader({ appName, user }) { return ( header span{appName}/span span{user?.name}/span /header ); }这种方法比直接在客户端组件里访问process.env要安全得多也符合 Next.js 官方的架构推荐。数据流是服务端读变量 - 计算结果 - 传给客户端而不是变量本身传给客户端。4. 运行时读取环境变量为什么 process.env 在客户端会失效4.1 构建时替换与运行时读取的本质区别前面提到了 Next.js 会把process.env.XXX在构建阶段直接替换为具体值。这个机制在大多数情况下够用但它有一个致命缺陷构建产物是绑定特定环境变量的没法做到同一份构建产物在不同环境中动态切换变量。举个实际场景你的项目要部署到三个不同的服务器每台服务器的 API 地址都不同比如 A 服务器指向 A 机房B 服务器指向 B 机房。如果使用标准的next build构建方式你需要为每台服务器分别执行一次构建因为NEXT_PUBLIC_API_URL在构建时就被写死在代码里了。这对多机房部署、灰度发布、SaaS 多租户场景来说非常痛苦。服务端的情况稍微好一点Next.js 在 Node.js 运行时读取process.env是真实读取系统环境变量所以服务端变量理论上可以做到一次构建到处运行。但客户端变量不行它只能构建时内联。为了在客户端做到运行时动态读取业界有几个常见方案通过一个服务端接口动态获取配置比如/api/config返回当前环境的配置信息客户端在启动时 fetch 一次在 HTML 中注入全局变量比如通过next.config.js的env字段或者自定义_document.tsx在渲染时加入script标签写入window.__CONFIG__使用public/runtime-config.js这个约定的运行时配置文件其中方案三是我用得最多的。具体做法是在public目录下放一个runtime-config.js文件内容格式如下window.__RUNTIME_CONFIG__ { API_BASE_URL: https://api.example.com, FEATURE_FLAG_A: true, };然后在_document.tsx里引用这个脚本// pages/_document.tsx (Pages Router) import { Html, Head, Main, NextScript } from next/document; export default function Document() { return ( Html Head / body script src/runtime-config.js / Main / NextScript / /body /Html ); }在客户端组件里读取const config window.__RUNTIME_CONFIG__ ?? {}; const apiBaseUrl config.API_BASE_URL;这个方案的核心思路是让运行时配置文件作为一个独立的静态资源存在部署时只需要针对不同环境替换public/runtime-config.js这一个文件即可无需重新构建应用。我在多机房部署的项目里就是靠这个方案解决了构建产物复用问题。App Router 下没有_document.tsx可以自定义但你可以用app/layout.tsx里的script标签来实现等价效果// app/layout.tsx export default function RootLayout({ children }) { return ( html body script src/runtime-config.js / {children} /body /html ); }4.2 next.config.js 中的 env 字段与 publicRuntimeConfigNext.js 在配置文件里也提供了两个环境变量相关的配置项env和publicRuntimeConfig。// next.config.js module.exports { env: { CUSTOM_KEY: my-value, }, publicRuntimeConfig: { API_BASE_URL: process.env.API_BASE_URL || https://default.example.com, }, };env字段的值会在构建时替换到代码中的process.env.CUSTOM_KEY行为等价于.env文件但它是写在配置文件里的。这种方式不算推荐因为把配置硬编码在next.config.js里既不好维护也容易泄露到代码库。publicRuntimeConfig则是 Next.js 官方早期推荐的运行时配置方案只有 Pages Router 支持通过next/config模块读取import getConfig from next/config; const { publicRuntimeConfig } getConfig(); // publicRuntimeConfig.API_BASE_URL但这个方案在 App Router 下已经不能用了next/config仅兼容 Pages Router而且坦白说官方后续也不怎么推荐publicRuntimeConfig更主流的做法还是用环境变量加构建时内联或者用前面说的运行时配置文件方案。所以我的建议比较直接新项目一律用环境变量体系不要在 next.config.js 里藏一些隐式配置。配置文件只负责加载时读取process.env然后传给需要的位置而不是把值硬编码在 JS 文件里。4.3 踩坑实录Docker 部署时环境变量为什么不生效用 Docker 部署 Next.js 应该是目前最常见的运维方式了。我遇到过好几个团队反馈同一个问题我已经在 docker run 命令里通过 -e 环境变量传参了容器也启动了但页面里NEXT_PUBLIC_相关变量打印出来是 undefined。这个问题的根子是如果 Dockerfile 里执行了next build那么构建阶段就需要这些变量运行时传参已经晚了。正确的 Dockerfile 写法要考虑两个阶段# 构建阶段 FROM node:20-alpine AS builder WORKDIR /app COPY package.json package-lock.json ./ RUN npm ci COPY . . # 需要在此处传入 NEXT_PUBLIC 变量 ARG NEXT_PUBLIC_API_URLhttps://api.example.com ENV NEXT_PUBLIC_API_URL$NEXT_PUBLIC_API_URL RUN npm run build # 运行阶段 FROM node:20-alpine AS runner WORKDIR /app ENV NODE_ENVproduction COPY --frombuilder /app/.next/standalone ./ COPY --frombuilder /app/.next/static ./.next/static COPY --frombuilder /app/public ./public # 运行时变量只需服务端能读取的 ENV DATABASE_URLyour-db-url ENV API_SECRETyour-secret EXPOSE 3000 CMD [node, server.js]看到区别了吗NEXT_PUBLIC_前缀的变量必须在构建阶段传入ENV或ARG写在RUN npm run build之前而纯服务端变量如数据库 URL、密钥可以放在运行阶段因为它们是在 Node.js 进程运行时才读取的。如果你希望同一个镜像能在不同环境中复用那么NEXT_PUBLIC_变量就不适合在构建阶段写死这时可以回到第 4.1 节说的public/runtime-config.js方案。在 Dockerfile 的运行阶段把runtime-config.js挂载进容器docker run -v /host/path/runtime-config.js:/app/public/runtime-config.js -p 3000:3000 my-image这样同一个镜像、不同环境、不同配置文件完全不需要重新构建。5. 敏感信息保护与安全检查清单5.1 哪些信息绝对不能放进 .env 并提交到代码仓库看了一圈周围的项目最常见的安全事故源头就是.env文件被提交到了 Git 仓库。很多知乎、掘金上的教程为了演示方便直接贴出了包含真实密钥的.env文件新手照抄就容易出事。我的硬性清单如下数据库连接字符串特别是带用户名密码的第三方服务 Secret Key如 Stripe Secret Key、AWS Secret Access Key、OpenAI API KeyJWT 签名密钥内部系统之间的鉴权 Token任何人都能通过公开渠道查到的高权限账号密码这些信息一旦被提交到 Git 历史里就算你之后删掉了文件、改了密码攻击者仍然可以从历史记录里翻出来。Git 历史是不会自动抹除的除非你用git filter-repo之类的工具重写历史。正确做法是项目根目录的.gitignore文件里必须包含.env*.local、.env*.production等敏感文件模式提供一个.env.example文件作为模板里面只有变量名和示例值或空值提交到仓库供团队参考对于密钥类信息使用 Vercel 的 Environment Variables、GitHub Actions Secrets、AWS Secrets Manager 等专门的密钥管理工具标准.gitignore部分内容.env .env.* !.env.example注意第二行和第三行的组合!.env.example是豁免规则确保.env.example正常提交。5.2 客户端环境变量的安全边界NEXT_PUBLIC 的三种误用我总结了一下身边团队最容易出现的三种NEXT_PUBLIC_误用场景误用一存放真实 API 密钥NEXT_PUBLIC_GOOGLE_MAPS_API_KEYAIzaSy...这是我见过最多的。Google Maps 的 Key 如果在前端暴露攻击者可以直接拿去刷你的额度一个月给你刷出几千美金的账单。Google Cloud Console 后台确实能限制 referrer但即便这样密钥一旦公开仍然存在被滥用风险。误用二存放内部服务地址NEXT_PUBLIC_INTERNAL_APIhttp://10.0.0.4:8080有些公司内部 API 不经过公网负载均衡直接暴露在内网 IP 上。如果你把内网地址打进客户端包用户浏览器如果恰好在公司内网这些信息就等于是白送的内网入口提示。误用三隐藏业务逻辑比如把某个管理后台的开关、某个活动页的起始时间写在NEXT_PUBLIC_变量里以为这样用户看不到。这类信息只要在前端代码里出现用户就能通过源码看到根本谈不上隐藏。注意所有NEXT_PUBLIC_变量会直接出现在浏览器开发者工具 - Sources 或 network 请求中请默认认为任何人都能看见在这个前提下再决定是否能加前缀。5.3 服务端环境变量的泄露渠道Server Actions 与 Route Handlers有些人以为只要不加NEXT_PUBLIC_前缀服务端变量就绝对安全。这个想法过于乐观了。在 App Router 架构下服务端环境变量泄露通常发生在以下几个渠道渠道一服务端组件抛出的错误信息如果服务端组件在读取process.env.DATABASE_URL时抛错且错误信息没有做脱敏处理Next.js 在开发模式下会把整个错误堆栈可能包含数据库连接串、SQL 语句渲染到页面上。开发环境还好如果生产环境也开启了错误详情或者被代理误转发密钥就泄露了。渠道二Server Actions 的参数在客户端暴露Server Actions 是 RPC 调用虽然执行在服务端但函数的参数会以加密 payload 的形式从客户端传来。如果你写了一个 Server Action 接收用户的某个输入然后在函数内部直接拼接出了process.env.SECRET并塞进返回结果里那这个 Secret 就等于变相发给了客户端。渠道三在客户端组件中意外地穿传服务端变量我见过这样的代码// 服务端组件 import ClientComponent from ./ClientComponent; // 这里的 secret 会直接传给 ClientComponent 的 props const secret process.env.SECRET_KEY; return ClientComponent secret{secret} /;服务端组件确实可以读取secret但把它作为 props 传给客户端组件后这个值就会被打进客户端包。这是非常隐蔽的一个泄露方式而且 ESLint 不会报错。我的习惯是在写代码时明确区分凡是传给客户端组件的 props都必须假定是公开数据。5.4 实战排查如何验证你的环境变量没有泄露有段时间我对项目的安全性心里没底于是自己整理了一套简单的排查步骤分享出来首先构建项目npm run build然后用 grep 检查产物中是否出现了敏感关键字# 在 .next 目录中搜索可能的密钥模式 grep -r sk-1234\|AKIA\|BEGIN RSA PRIVATE KEY .next/ 2/dev/null | head -20更普遍的做法是搜索process.env的所有引用确认没有出现非NEXT_PUBLIC_前缀的变量被打包grep -ro process\.env\.[A-Z_]* .next/static 2/dev/null | sort -u如果输出里出现了类似DATABASE_URL、SECRET_KEY这些非NEXT_PUBLIC_前缀的变量名基本可以断定泄露了。另一种方式是在浏览器中打开构建后的 HTML查看script标签加载的 JS 文件源码直接搜索一些环境变量的值。我自己把这个排查做成了一个简单的 CI 检查脚本每次发布前自动跑一遍发现问题直接阻断构建。虽然被人说过过度紧张但多一次检查总比线上事故好。6. 不同部署模式下的环境变量配置策略6.1 Vercel 部署最省心的配置方式Vercel 是 Next.js 的官方推荐部署平台对环境变量的支持非常完善。在 Vercel 项目控制台的 Settings - Environment Variables 中你可以针对不同的环境Production、Preview、Development配置不同的变量值。Vercel 有个很实用的对齐机制你在本地.env.local里维护的变量可以通过 Vercel CLI 一键同步到云端vercel env pull .env.development.local这会从 Vercel 项目里拉取开发环境变量到你本地。如果你在团队协作团队成员只需要执行这一条命令就能拿到云端维护的最新变量不需要互相传文件。Vercel 部署时需要注意部署到 Preview 环境的next build是在 Vercel 云端服务器执行的所以你想要NEXT_PUBLIC_变量被正确内联需要在云端配置中给 Preview 环境也设置对应的变量否则构建产物里就是空值。6.2 自建服务器 PM2 的经典方案如果你倾向自建服务器用 PM2 管理 Next.js 进程那环境变量的配置有几个层面PM2 配置文件ecosystem.config.js中的env字段适合设置服务端变量系统环境变量如/etc/environment或者 systemd service 文件中的Environment适合更底层的配置运行时配置文件对应客户端动态变量一个比较稳妥的做法是把服务端关键变量写入 systemd 的 service 定义中这样即使服务进程被重启也能稳定加载[Service] EnvironmentDATABASE_URLpostgres://user:passhost/db EnvironmentJWT_SECRETyour-secret ExecStart/usr/bin/node /var/www/project/server.js Restartalways注意 systemd 的 service 文件里如果变量值包含特殊字符如#、$、空格需要用双引号包裹。我在这上面吃过亏一个包含了!的数据库密码导致整条配置解析失败杀掉进程反复启动都起不来排查了半天才发现是 systemd 解析转义的问题。自建服务器场景下.env.production文件可以被next start读取但你需要确保这个文件不会出现在 Git 仓库里部署时单独通过 scp 或 Ansible 等工具推送到服务器。6.3 Docker Compose 多服务编排如果你想用 Docker Compose 编排多个服务比如 Next.js PostgreSQL Redis环境变量的组织方式会稍微复杂一点。一个常见的正确姿势services: web: image: my-next-app:latest ports: - 3000:3000 environment: DATABASE_URL: ${DATABASE_URL} REDIS_URL: ${REDIS_URL} env_file: - .env.production.local注意这里有三层来源docker-compose.yml里用${VAR}引用的宿主环境变量、env_file指定的文件变量、以及镜像构建时已经内联的NEXT_PUBLIC_变量。很多人容易搞混这三者的关系和生效时机。构建时内联的变量在镜像构建阶段就已经固定运行阶段的environment和env_file无法改变它。而服务端变量则完全遵循运行时的优先级规则容器环境变量 env_file文件。我的建议是不要在 docker-compose.yml 中硬编码任何敏感值统一用${VAR}引用宿主环境变量或外部.env文件这样密钥管理可以集中到一个地方降低泄露面。6.4 灰度发布与多环境切换的实战方案最后一个想聊的实战场景是多环境切换。假设你有一个管理后台需要同时运行 staging 环境和 production 环境代码相同但 API 地址不同。由于NEXT_PUBLIC_变量是构建时内联的最简单粗暴的做法是分别构建两套产物。这在单机部署时可以接受但如果你的服务分布在多个节点每个节点都要构建一遍那可维护性就很差了。我之前在重构一个多节点部署项目时把客户端动态配置全部迁移到了public/runtime-config.js方案然后通过 Nginx 做不同路由下的文件代理。例如staging.example.com指向runtime-config.staging.jsexample.com指向runtime-config.production.jsNginx 配置大致如下server { listen 80; server_name example.com; location /runtime-config.js { alias /var/www/configs/runtime-config.production.js; } location / { proxy_pass http://127.0.0.1:3000; } } server { listen 80; server_name staging.example.com; location /runtime-config.js { alias /var/www/configs/runtime-config.staging.js; } location / { proxy_pass http://127.0.0.1:3000; } }这套方案的好处是同一份 Next.js 构建产物可以同时服务多个环境切换配置只需要切换 Nginx 的文件代理即可不需要重新构建和重新发布应用。缺点也需要注意runtime-config.js是浏览器端公共文件不能放任何敏感信息只能放公开可读的配置项。7. 工程化实践环境变量的组织、校验与团队协作7.1 zod/zod-env给环境变量提出类型要求环境变量在项目里往往是问题最隐蔽的隐式依赖——你不在代码里声明它代码也编译得过去直到运行时才发现undefined。所以我推荐给项目加上一层环境变量校验趁构建阶段把缺口暴露出来。目前在 Next.js 项目里主流的方案是结合zod写一个环境变量校验模块// lib/env.ts import { z } from zod; const envSchema z.object({ NODE_ENV: z.enum([development, test, production]).default(development), DATABASE_URL: z.string().url(), JWT_SECRET: z.string().min(32), NEXT_PUBLIC_API_URL: z.string().url(), SMTP_HOST: z.string().optional(), SMTP_PORT: z.coerce.number().int().positive().default(587), }); const parsedEnv envSchema.safeParse(process.env); if (!parsedEnv.success) { console.error(环境变量校验失败请检查以下变量); console.error(parsedEnv.error.flatten().fieldErrors); throw new Error(Invalid environment variables); } export const env parsedEnv.data;然后用env.DATABASE_URL替代直接process.env.DATABASE_URL。好处很明显变量缺失或格式不符合预期时构建或启动阶段就会直接报错而不是等到运行时踩到空值。我用zod还有一个额外收获——所有环境变量的结构和用途都在一个文件里集中描述新成员接手项目时看这个文件就能快速理解项目的配置全貌比翻代码上下文高效得多。7.2 .env.example 文件模板的维护团队协作里.env.example文件是一个经常被忽略但极其重要的产物。它应该包含所有需要配置的变量名、说明文字和示例值示例值不能用真实值。我习惯的格式是这样的# 数据库连接 DATABASE_URLpostgresql://user:passwordlocalhost:5432/mydb # JWT 签名密钥至少32位随机字符串 JWT_SECRETplease-change-me-to-a-random-string # 公网可访问的 API 地址NEXT_PUBLIC_ 前缀会暴露在客户端 NEXT_PUBLIC_API_URLhttps://api.example.com # 可选SMTP 服务配置 SMTP_HOST SMTP_PORT587每行变量后面尽量带一句注释说明用途和值格式。做这一步的收益会在两个时间点集中体现项目成员新入职时以及项目换季维护再捡起来时你永远会忘记自己当初定义的变量到底是干嘛的。7.3 环境变量的命名规范与代码审查我给团队的命名规范里明确了几条约定表示布尔的变量用IS_前缀如IS_PRODUCTION_ENABLED带NEXT_PUBLIC_前缀的变量只允许存储公开且非敏感的配置禁止在组件代码中直接使用process.env.XXX统一通过lib/env.ts的env对象访问新增加环境变量时必须同步更新.env.example和校验 schema 文件代码审查时我会重点关注两件事新增的process.env引用是否带有NEXT_PUBLIC_前缀防止不小心把服务端变量暴露以及变量的默认值是否存在回退风险。后者其实才是很多线上事故的真凶——代码里如果写了process.env.API_URL || http://localhost:3000这种兜底逻辑那么任何环境下变量缺失时应用都会静默地连到 localhost而不是报错提醒你配置缺失。我后续更倾向的做法是不设非必要默认值让校验层直接拦截。7.4 本地开发与多人协作的细节优化最后分享几个本地开发的小优化点使用loadEnvFiles: false开关场景。如果你在用 Docker 开发环境宿主机和容器内的环境变量不同且容器内已经由 compose 注入了正确的变量这时可以在next.config.js里关闭 .env 文件加载避免本地文件不小心覆盖容器变量module.exports { loadEnvFiles: false, };不同类型变量放不同文件。我自己的习惯是NEXT_PUBLIC_变量放.env或.env.development因为它们不影响安全敏感变量放.env.local不提交仓库。这样即便有人误提交了.env.development泄露出最坏也只是几个公开配置项。利用.env.local做差异覆盖。比如团队约定.env里存放统一的基础配置如NEXT_PUBLIC_APP_NAME每个开发者在自己的.env.local里覆盖本地调试相关的变量如数据库端口、日志级别互不干扰。这套组合拳打下来我在 Next.js 项目中因为环境变量引发的线上事故几乎降到零。踩过最惨的坑基本都是绕开了这些规范之后踩的所以我把它们整理出来希望能帮你避开那些我看过的、亲历过的教训。这类问题排查起来非常消耗时间而且往往是隐蔽的、间歇性的越早把规范建立起来后面越省心。