next-runtime-env核心API env()全解析一个函数打通浏览器与服务器环境变量读取【免费下载链接】next-runtime-envNext.js Runtime Environment Configuration - Populates your environment at runtime rather than build time.项目地址: https://gitcode.com/gh_mirrors/ne/next-runtime-envnext-runtime-env 是一个 Next.js 运行时环境变量配置库核心 APIenv()函数让你不再受限于构建时注入——同一个函数调用浏览器里读NEXT_PUBLIC_前缀的公开变量服务器端读process.env中的任意变量真正实现「一次构建多环境部署」。为什么需要 next-runtime-env 的 env() 函数 Next.js 默认在构建时就把NEXT_PUBLIC_变量的值「烧录」进 JS 包。这意味着换个环境测试/生产就得重新构建一次违反「构建一次部署多处」Build once, deploy many的持续交付原则服务器变量改了值浏览器里的包不会变next-runtime-env的思路是把环境变量注入时机从构建时推迟到运行时——服务器每次请求时读取最新的process.env并通过内联脚本塞进页面浏览器随取随用。而env()就是这一切的统一读取入口。快速上手3 步在 Next.js 项目中启用 env() 第 1 步安装npm install next-runtime-env第 2 步在根布局的head中挂载PublicEnvScript// src/app/layout.tsx import { PublicEnvScript } from next-runtime-env; export default function RootLayout({ children }) { return ( html langzh-CN head PublicEnvScript / /head body{children}/body /html ); }第 3 步在任何位置用env()读取变量import { env } from next-runtime-env; export function MyComponent() { const NEXT_PUBLIC_FOO env(NEXT_PUBLIC_FOO); return div{NEXT_PUBLIC_FOO}/div; }官方推荐Script 方案因为env()可以脱离 React 上下文使用如useEffect里发请求、工具函数里读配置如果你只待在 React 组件内也可以选 Context 方案PublicEnvProvideruseEnvContextHook。完整步骤见 GETTING_STARTED.md。源码级解析env() 的浏览器 / 服务器双路机制 env()的完整实现只有 20 多行核心逻辑在src/script/env.tsexport function env(key: string): string | undefined { if (isBrowser()) { if (!key.startsWith(NEXT_PUBLIC_)) { throw new Error( Environment variable ${key} is not public and cannot be accessed in the browser., ); } return window.__ENV[key]; } noStore(); return process.env[key]; }它内部按运行环境走了两条完全不同的路运行环境数据来源安全约束 浏览器全局对象window.__ENV仅允许NEXT_PUBLIC_前缀否则直接抛错️ 服务器Node 的process.env无限制可读取任意变量浏览器路径的幕后细节isBrowser()src/helpers/is-browser.ts通过检测window.__ENV是否存在来判断是否在浏览器中PublicEnvScriptsrc/script/public-env-script.tsx在页面渲染时把运行时的最新环境变量序列化为内联脚本window[__ENV] {...}写入head见src/script/env-script.tsx变量统一挂载在__ENV键上键名定义在src/script/constants.ts。服务器路径的关键一行noStore()它调用 Next.js 的unstable_noStore取消响应缓存确保每次请求都拿到最新的环境变量——这正是「运行时」而非「构建时」的核心保障。常见坑位使用 env() 前必看的 3 个要点 ⚠️1. 在浏览器里读非公开变量会直接抛错env(DB_PASSWORD); // ❌ 浏览器中抛错not public and cannot be accessed in the browser这是故意的安全设计。如果你确实要把某个无前缀变量暴露给浏览器用工具函数makeEnvPublicsrc/utils/make-env-public.ts给它自动加NEXT_PUBLIC_前缀makeEnvPublic(API_URL); // process.env.API_URL → process.env.NEXT_PUBLIC_API_URL2. 敏感信息永远不要加NEXT_PUBLIC_前缀凡是NEXT_PUBLIC_开头的变量最终都会出现在浏览器页面的 HTML 里任何人都能看到。密钥、Token 类变量只应留在服务器端通过env()的服务器路径读取。3. 自定义暴露哪些变量默认只暴露NEXT_PUBLIC_前缀的变量。想精细控制暴露范围参考 EXPOSING_CUSTOM_ENV.md想批量公开无前缀变量参考 MAKING_ENV_PUBLIC.md。版本怎么选next-runtime-env 与 Next.js 版本对照 next-runtime-env 版本适配的 Next.js1.xNext.js 12/13Pages Router2.xNext.js 13App Router3.xNext.js 14含高级缓存支持✅ 推荐开发时仍可直接使用.env文件与标准 Next.js 开发体验保持一致。小结 env()用一个极简的函数签名抹平了 Next.js 客户端与服务端的环境变量读取差异✅ 浏览器读window.__ENV服务端读process.env同一份代码两端通用✅ 运行时注入 noStore()保证「一次构建到处部署」✅ 强制NEXT_PUBLIC_前缀校验把安全边界写进了 API 本身如果你的项目还在为「改个环境变量就要重新构建」头疼next-runtime-env值得一试。【免费下载链接】next-runtime-envNext.js Runtime Environment Configuration - Populates your environment at runtime rather than build time.项目地址: https://gitcode.com/gh_mirrors/ne/next-runtime-env创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考