next-runtime-env进阶实战用EnvScript把任意自定义环境变量安全注入浏览器【免费下载链接】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 应用在「运行时」读取环境变量的轻量方案核心亮点是EnvScript组件——它能把你指定的任意自定义环境变量不限于NEXT_PUBLIC_前缀安全地注入到浏览器中真正做到「一次构建、处处部署」。本文带你从痛点讲起用最少的代码完成从「公开变量」到「任意变量」的安全注入。为什么 Next.js 的环境变量总在构建时写死传统 Next.js 里公开的process.env变量会在npm run build时被内联进产物代码由此带来两个尴尬换个环境就要重新构建测试、生产环境变量不同就得各打一份包。难以一次构建、多处部署这本是持续交付推崇的最佳实践可惜原生 Next.js 前端很难做到。next-runtime-env的思路很直接把变量读取推迟到页面加载那一刻于是同一份构建产物可以在任何环境跑起来。快速上手3 步让运行时环境变量生效 建议搭配 Next.js 14 使用对应next-runtime-env3.x缓存支持最佳。第一步 安装依赖用你顺手的包管理器安装即可npm install next-runtime-env第二步 在根布局注入脚本只需在根布局如src/app/layout.tsx的head中放入一个组件import { PublicEnvScript } from next-runtime-env; export default function RootLayout({ children }) { return ( html langen head PublicEnvScript / /head body{children}/body /html ); }PublicEnvScript会自动把所有NEXT_PUBLIC_开头的变量送到浏览器无需任何额外配置。第三步 用 env() 读取变量在任意组件客户端或服务端中直接读取import { env } from next-runtime-env; export function MyPage() { const FOO env(NEXT_PUBLIC_FOO); return div值{FOO}/div; }到这里你已经拥有了一套「运行时」环境变量能力。真正的进阶玩法在下面 进阶核心用 EnvScript 注入任意自定义变量默认情况下浏览器只能拿到NEXT_PUBLIC_前缀的变量。若想额外公开BAR、BAZ这类自定义命名的变量就交给EnvScript组件。EnvScript 的工作原理EnvScript会把你传入的普通对象序列化为一小段内联脚本写入window.__ENV。关键特性内容完全由你决定传什么变量浏览器就能看到什么。⚡运行时求值对象里的值在服务端渲染时才会被读取因此永远是最新值。安全注入自定义变量的最小示例import { unstable_noStore as noStore } from next/cache; import { EnvScript } from next-runtime-env; export default function RootLayout({ children }) { noStore(); // 关闭缓存确保每次请求都拿到最新值 return ( html langen head EnvScript env{{ NEXT_PUBLIC_: process.env.NEXT_PUBLIC_FOO, BAR: process.env.BAR, // 自定义变量 BAZ: process.env.BAZ, // 自定义变量 }} / /head body{children}/body /html ); }之后同样用env(BAR)就能在浏览器里读到它——是不是很灵活安全细节别把密钥误发到浏览器安全是环境变量的生命线。next-runtime-env内置了一道「护栏」️浏览器侧白名单在浏览器环境调用env(BAR)时若该变量没有NEXT_PUBLIC_前缀会直接抛错从机制上阻止你把私有变量暴露给前端。服务端无限制在服务端route handler、服务端组件env()读取process.env可访问全部变量适合存放 API 密钥、数据库凭据等。一句话原则凡是会出现在浏览器的变量都必须显式标记为公开。EnvScript的env对象就是你手动把关的地方——只写你真正想公开的。两种注入方式怎么选Script vs Contextnext-runtime-env提供了两套机制对应不同场景方案组件 / 方法适用场景特点脚本式推荐PublicEnvScript/EnvScript需要在 React 上下文之外读取写入window.__ENV全局可用上下文式PublicEnvProvider/EnvProvider只在组件树内使用通过useEnvContext()Hook 读取若要在工具函数、第三方 SDK 里读变量选脚本式若只想在组件内使用上下文式更React 化。注意把 Provider 放在服务端组件中再用 Hook 读取import { useEnvContext } from next-runtime-env; export function MyComp() { const { NEXT_PUBLIC_FOO } useEnvContext(); return div{NEXT_PUBLIC_FOO}/div; }实用技巧makeEnvPublic 让私有变量变公开有时变量名无法控制比如第三方要求叫STRIPE_KEY又不想手动改前缀。makeEnvPublic可以批量把私有变量「升格」为公开// next.config.js const { makeEnvPublic } require(next-runtime-env); makeEnvPublic([FOO, BAR]); // 升格为 NEXT_PUBLIC_FOO / NEXT_PUBLIC_BAR它会自动加前缀并打印日志提示方便核对。版本兼容清单一次看清选错版本会白忙一场用下面这张表 30 秒定位next-runtime-env 版本适配的 Next.js说明1.x12 / 13Pages Router页面路由2.x13App Router应用路由3.x14支持高级缓存推荐常见问题 FAQQEnvScript和PublicEnvScript到底差在哪APublicEnvScript自动收集所有NEXT_PUBLIC_变量EnvScript则由你手动指定要公开哪些变量包含任意自定义名。Q为什么我的变量在浏览器里是undefinedA多半是布局被缓存了。加上noStore()或确保页面走动态渲染保证每次请求都重新求值。Q能在中间件middleware里用吗A可以。next-runtime-env的等构设计覆盖了服务端、浏览器与中间件场景脚本式方案在中间件同样适用。到这里你已经掌握了next-runtime-env的精髓用EnvScript把任意自定义环境变量安全地送进浏览器同时用内置护栏守住安全底线。想加深体感可以去示例目录examples/with-app-router-script里跑一遍跟着 README 的变量示例观察客户端与服务端的不同取值。【免费下载链接】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），仅供参考