运行时配置
Nuxt 提供了运行时配置 API，用于在应用程序中暴露配置和密钥。
暴露配置
要向应用程序的其他部分暴露配置和环境变量，你需要在 nuxt.config 文件中使用 runtimeConfig 选项定义运行时配置。
nuxt.config.ts
export default defineNuxtConfig({
runtimeConfig: {
// 仅在服务器端可用的私有密钥
apiSecret: '123',
// public 中的密钥也会暴露到客户端
public: {
apiBase: '/api'
}
}
})
当将 apiBase 添加到 runtimeConfig.public 时，Nuxt 会将其添加到每个页面的有效载荷中。我们可以在服务器和浏览器中统一访问 apiBase。
const runtimeConfig = useRuntimeConfig()
console.log(runtimeConfig.apiSecret)
console.log(runtimeConfig.public.apiBase)
公共运行时配置可在 Vue 模板中通过
$config.public 访问。序列化
运行时配置在传递给 Nitro 之前会被序列化。这意味着任何无法序列化和反序列化的内容（如函数、Set、Map 等）不应在 nuxt.config 中设置。
不要从 nuxt.config 向应用程序传递不可序列化的对象或函数，而是可以将此类代码放在 Nuxt 或 Nitro 插件或中间件中。
环境变量
提供配置的最常见方式是使用 环境变量。
Nuxt CLI 在开发、构建和生成时内置支持读取
.env 文件。但当你运行构建后的服务器时，不会读取 .env 文件。运行时配置值在运行时会被匹配的环境变量自动替换。
有两个关键要求：
- 你需要的变量必须在
nuxt.config中定义。这确保任意环境变量不会暴露到应用程序代码中。 - 只有特定命名的环境变量才能覆盖运行时配置属性。即，以
NUXT_开头的大写环境变量，使用_分隔键和大小写变化。
将
runtimeConfig 值的默认值设置为不同名称的环境变量（例如将 myVar 设置为 process.env.OTHER_VARIABLE）仅在构建时有效，在运行时会失效。
建议使用与 runtimeConfig 对象结构匹配的环境变量。示例
.env
NUXT_API_SECRET=api_secret_token
NUXT_PUBLIC_API_BASE=https://nuxtjs.org
nuxt.config.ts
export default defineNuxtConfig({
runtimeConfig: {
apiSecret: '', // 可被 NUXT_API_SECRET 环境变量覆盖
public: {
apiBase: '', // 可被 NUXT_PUBLIC_API_BASE 环境变量覆盖
}
},
})
读取配置
Vue 应用
在 Nuxt 应用的 Vue 部分，你需要调用 useRuntimeConfig() 来访问运行时配置。
客户端和服务器端的行为不同：
- 在客户端，只有
runtimeConfig.public和runtimeConfig.app（Nuxt 内部使用）中的键可用，且该对象是可写且响应式的。 - 在服务器端，整个运行时配置都可用，但为避免上下文共享，它是只读的。 ::
pages/index.vue
<script setup lang="ts">
const config = useRuntimeConfig()
console.log('运行时配置：', config)
if (import.meta.server) {
console.log('API 密钥：', config.apiSecret)
}
</script>
<template>
<div>
<div>查看开发者控制台！</div>
</div>
</template>
安全提示： 注意不要通过渲染或将其传递给
useState 等方式将运行时配置密钥暴露到客户端。插件
如果要在任何（自定义）插件中使用运行时配置，可以在defineNuxtPlugin 函数中使用 useRuntimeConfig()。plugins/config.ts
export default defineNuxtPlugin((nuxtApp) => {
const config = useRuntimeConfig()
console.log('API 基础 URL：', config.public.apiBase)
});
服务器路由
你也可以在服务器路由中使用useRuntimeConfig 访问运行时配置。server/api/test.ts
export default defineEventHandler(async (event) => {
const { apiSecret } = useRuntimeConfig(event)
const result = await $fetch('https://my.api.com/test', {
headers: {
Authorization: `Bearer ${apiSecret}`
}
})
return result
})
为运行时配置添加类型
Nuxt 尝试使用 unjs/untyped 从提供的运行时配置自动生成 TypeScript 接口。但你也可以手动为运行时配置添加类型：index.d.ts
declare module 'nuxt/schema' {
interface RuntimeConfig {
apiSecret: string
}
interface PublicRuntimeConfig {
apiBase: string
}
}
// 增强类型时，确保导入/导出某些内容是很重要的
export {}
nuxt/schema 为最终用户提供了便利，用于访问项目中 Nuxt 使用的模式版本。模块作者应改为增强 @nuxt/schema。