跳到主要内容
Nuxt 中文
开始使用

运行时配置

Nuxt 提供了一套运行时配置 API，以在你的应用内暴露配置和密钥。

暴露配置

要将配置和环境变量暴露给应用的其余部分，你需要在 nuxt.config 文件中，使用 runtimeConfig 选项来定义运行时配置。

nuxt.config.ts
export default defineNuxtConfig({
  runtimeConfig: {
    // 仅在服务端可用的私有密钥
    apiSecret: '123',
    // public 内的键，也会被暴露到客户端
    public: {
      apiBase: '/api',
    },
  },
})

当把 apiBase 添加到 runtimeConfig.public 时，Nuxt 会把它添加到每个页面的 payload 中。我们可以在客户端和浏览器中通用地访问 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 文件不会被读取。阅读更多

运行时配置值会在运行时被匹配的环境变量自动替换。

有两个关键要求：

  1. 你想要的变量必须在你的 nuxt.config 中定义。这确保了任意的环境变量不会被暴露给你的应用代码。
  2. 只有特定命名的环境变量可以覆盖一个运行时配置属性。也就是以 NUXT_ 开头的大写环境变量，并使用 _ 来分隔键名和大小写变化。
将 runtimeConfig 的默认值设置为不同名称的环境变量（例如将 myVar 设置为 process.env.OTHER_VARIABLE），只会在构建时生效，并在运行时失效。建议使用与你 runtimeConfig 对象结构相匹配的环境变量。
环境变量的值会通过 destr 自动转换为它们的 JavaScript 类型。例如，NUXT_MY_VAR=4848e0 会变成数字 4848。要让某个值保持为字符串，环境变量本身必须包含字面量双引号：在 .env 文件中，写成 NUXT_MY_VAR='"4848e0"'；当直接设置变量时（在 shell、Dockerfile 或托管仪表盘中），请确保引号是值的一部分，且没有被 shell 剥离（例如 NUXT_MY_VAR='"4848e0"' node .output/server/index.mjs）。
观看 Alexander Lichter 的视频，展示开发者使用 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 内部使用）中的键可用，并且该对象既可读写也具有响应性。
  • 在服务端，整个运行时配置都可用，但它是只读的，以避免上下文共享。
app/pages/index.vue
<script setup lang="ts">
const config = useRuntimeConfig()

console.log('Runtime config:', config)
if (import.meta.server) {
  console.log('API secret:', config.apiSecret)
}
</script>

<template>
  <div>
    <div>检查开发者控制台！</div>
  </div>
</template>
安全提示： 小心不要通过渲染它们或将它们传入 useState 来把运行时配置的键暴露到客户端。

插件

如果你想在任意（自定义）插件中使用运行时配置，可以在你的 defineNuxtPlugin 函数内部使用 useRuntimeConfig()。

app/plugins/config.ts
export default defineNuxtPlugin((nuxtApp) => {
  const config = useRuntimeConfig()

  console.log('API base URL:', config.public.apiBase)
})

服务端路由

你也可以在服务端路由中使用 useRuntimeConfig 访问运行时配置。

server/api/test.ts
export default defineEventHandler(async (event) => {
  const { apiSecret } = useRuntimeConfig()
  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 在其项目中使用的 schema 版本。模块作者应该改为增强 @nuxt/schema。