Nitro Runtime Config 实战指南用环境变量在运行时动态覆盖服务端配置【免费下载链接】nitroNext Generation Server Toolkit. Create web servers with everything you need and deploy them wherever you prefer.项目地址: https://gitcode.com/GitHub_Trending/ni/nitroRuntime config运行时配置是 Nitro 提供的一套配置即代码、覆盖靠环境的机制你可以在nitro.config.ts中声明带默认值的配置结构在处理器中通过useRuntimeConfig()读取并在运行时用NITRO_前缀的环境变量逐项覆盖从而在不重新构建的情况下切换开发、预发、生产等不同环境的 API 地址、密钥与功能开关。本文以仓库中的 runtime-config 示例 为主线结合 Nitro 源码与单元测试带你完整掌握从定义、读取、覆盖到嵌套对象、自定义前缀、环境变量展开的整套用法。示例项目概览仓库中的 examples/runtime-config 是一个最小可运行的独立示例完整结构如下nitro.config.ts声明 runtime config 结构与默认值server.ts定义处理器并在其中读取运行时配置package.json提供nitro dev与nitro build两个脚本tsconfig.json通过extends: nitro/tsconfig继承 Nitro 的 TS 配置。运行示例只需要两步npm install npm run dev # 或 npm run build注意示例中serverDir: ./即服务端代码直接放在项目根目录server.ts就是入口处理器。第一步在 nitro.config.ts 中定义配置结构Runtime config 的第一步是在配置文件中声明结构并给出默认值。示例中只声明了一个apiKey字段import { defineConfig } from nitro; export default defineConfig({ serverDir: ./, runtimeConfig: { apiKey: , }, });这里apiKey的默认值是空字符串。在实际项目中它可以是 API 端点、第三方密钥、数据库连接信息或功能开关等任何因环境而异的值。值得强调的是runtime config 在构建期会被规范化处理。在源码 src/config/resolvers/runtime-config.ts 的normalizeRuntimeConfig中你的runtimeConfig会与 Nitro 内置的默认结构合并通过defu做浅层合并内置的app、nitro节点会自动注入最终形成一份完整的运行时配置对象。第二步在处理器中通过 useRuntimeConfig 读取运行时访问配置的 API 是useRuntimeConfig。示例的 server.ts 演示了最直接的用法import { defineHandler } from nitro; import { useRuntimeConfig } from nitro/runtime-config; export default defineHandler((event) { const runtimeConfig useRuntimeConfig(); return { runtimeConfig }; });useRuntimeConfig从nitro/runtime-config模块导入入口见 src/runtime/runtime-config.ts。它返回整个配置对象你可以直接返回它如本例、返回单个字段或在任意中间件、插件、任务中使用。从源码 src/runtime/internal/runtime-config.ts 可以看到其底层实现首次调用时通过getRuntimeConfig()读取虚拟模块#nitro/virtual/runtime-config中的默认配置并用applyEnv将环境变量覆盖进去然后缓存在函数属性_cached上后续调用直接返回缓存因此同一进程内多次调用是零成本的。第三步用 NITRO_ 前缀的环境变量覆盖默认值默认配置写死在代码里而运行时覆盖则交给环境变量。Nitro 约定所有覆盖 runtime config 的环境变量都必须以NITRO_开头。示例的注释文件 .env 展示了覆盖apiKey的方法# NEVER COMMIT SENSITIVE DATA. THIS IS ONLY FOR DEMO PURPOSES. NITRO_API_KEYsecret-api-key启动服务后处理器返回的runtimeConfig中的apiKey就不再是空字符串而是secret-api-key。键名映射规则camelCase ↔ UPPER_SNAKE_CASE配置键在代码中是 camelCase驼峰在环境变量中是 UPPER_SNAKE_CASE全大写加下划线。helloWorld对应NITRO_HELLO_WORLDapiKey对应NITRO_API_KEY。这一转换在源码中由applyEnv完成它先用scule库的snakeCase将键名转为下划线形式并toUpperCase()再拼接前缀去读取环境变量见 src/runtime/internal/runtime-config.ts。只有已声明的键才会生效一个重要的边界环境变量只能覆盖nitro.config.ts中已经声明的键无法仅凭环境变量引入新键。配置结构在构建期就已固定这是保证运行时行为可预期的前提。进阶一嵌套对象的覆盖Runtime config 天然支持嵌套对象任何深度的键都会以_连接生成环境变量名。官方配置文档 docs/1.docs/50.configuration.md 给出了完整示例import { defineConfig } from nitro; export default defineConfig({ runtimeConfig: { database: { host: localhost, port: 5432, }, }, });NITRO_DATABASE_HOSTdb.example.com NITRO_DATABASE_PORT5433此时useRuntimeConfig().database.host将返回db.example.comport返回5433。从源码 src/runtime/internal/runtime-config.ts 看applyEnv对嵌套对象递归处理如果配置值是对象且找到对应的扁平环境变量则该对象整个被环境值替换如果该层没有匹配的环境变量则继续向更深层递归。这一行为也被单元测试 test/unit/runtime-config.env.test.ts 所验证NITRO_FEATURE_OPTIONS_OPTION1env会精确覆盖feature.options.option1而option2保持默认值 123 不变。进阶二序列化约束与空值兜底Runtime config 的值必须可序列化即仅允许字符串、数字、布尔值、普通对象与数组。类实例、函数、Map等复杂类型会触发构建期警告。normalizeRuntimeConfig中的checkSerializableRuntimeConfigsrc/config/resolvers/runtime-config.ts会递归遍历配置遇到不可序列化类型时输出形如Runtime config option \xxx may not be able to be serialized. 的警告。对应地单元测试 test/unit/runtime-config.test.ts 验证了当runtimeConfig中混入new Map()时console.warn恰好被调用一次而纯可序列化配置不会产生任何警告。另一个兜底行为配置中值为undefined或null的键会被替换为空字符串这是provideFallbackValuessrc/config/resolvers/runtime-config.ts在构建期完成的避免运行时出现空引用。进阶三自定义二级环境变量前缀默认情况下除了NITRO_前缀Nitro 还支持一个二级前缀_即_API_TOKEN也能覆盖apiToken。如需换成自己的前缀可在 runtime config 的内置nitro.envPrefix键上声明import { defineConfig } from nitro; export default defineConfig({ runtimeConfig: { nitro: { envPrefix: APP_, }, apiToken: , }, });配置之后NITRO_API_TOKEN与APP_API_TOKEN都会作为候选覆盖来源。源码 src/runtime/internal/runtime-config.ts 中二级前缀altPrefix的解析优先级为runtimeConfig.nitro.envPrefix→ 环境变量NITRO_ENV_PREFIX→ 默认值_。进阶四环境变量展开Env Expansion如果你希望配置值内部引用其他环境变量可以开启实验性的环境变量展开功能。开启后字符串中的{{VAR_NAME}}占位符会在运行时被替换为对应环境变量的值import { defineConfig } from nitro; export default defineConfig({ experimental: { envExpansion: true, }, runtimeConfig: { url: https://{{APP_DOMAIN}}/api, }, });APP_DOMAINexample.com此时useRuntimeConfig().url会解析为https://example.com/api。若引用的环境变量不存在占位符会原样保留而非报错。这一逻辑对应源码中的_expandFromEnv与正则/\{\{([^{}]*)\}\}/gsrc/runtime/internal/runtime-config.ts并且在测试 test/unit/runtime-config.env.test.ts 中被覆盖包括默认关闭未命中保留原文多变量组合展开三种场景。开发与生产的正确姿势本地开发在项目根目录创建.env或.env.local文件。需要注意.env是在 Nitro 解析配置nitro dev/nitro build时加载的因此构建产物中的默认值已固定它不会在服务运行时被读取。已存在于系统环境中的变量优先级高于.env中的值。生产部署使用部署平台如 Vercel、Netlify、Cloudflare 等原生的环境变量管理机制在平台上设置NITRO_前缀的变量即可。由于运行时覆盖发生在进程启动阶段useRuntimeConfig首次调用时你不需要为不同环境重新构建同一份构建产物可以在任意环境运行。敏感信息示例文档特别强调NEVER COMMIT SENSITIVE DATA——不要把真实密钥提交进仓库.env应加入.gitignore生产密钥走平台变量。回顾完整的读写链路把示例与源码串起来一次运行时配置的完整链路是构建期normalizeRuntimeConfigsrc/config/resolvers/runtime-config.ts合并你声明的runtimeConfig与内置app/nitro结构替换空值为并校验可序列化性最终注入虚拟模块启动期处理器首次调用useRuntimeConfig()时getRuntimeConfigsrc/runtime/internal/runtime-config.ts读取虚拟模块并通过applyEnv应用环境变量覆盖结果缓存复用运行期整个应用处理器、中间件、插件、任务通过useRuntimeConfig()读取统一、覆盖后的配置视图。这套机制让配置默认值进代码、环境差异交给环境变量成为可能配合本文的嵌套对象、自定义前缀、环境变量展开三个进阶能力足以覆盖绝大多数多环境部署场景。完整的参考文档见 docs/1.docs/50.configuration.md更多多环境部署示例可参考 examples 目录下的其他示例项目。【免费下载链接】nitroNext Generation Server Toolkit. Create web servers with everything you need and deploy them wherever you prefer.项目地址: https://gitcode.com/GitHub_Trending/ni/nitro创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考