Lzh on GitHub

Runtime Config

Nuxt 提供了一个运行时配置 API，用于在你的应用程序中暴露配置和密钥。

暴露

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

nuxt.config.ts
export default defineNuxtConfig({
  runtimeConfig: {
    // The private keys which are only available within server-side
    apiSecret: '123',
    // Keys within public, will be also exposed to the client-side
    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 之前进行序列化。这意味着任何无法序列化和反序列化的内容（例如函数、Sets、Maps 等）都不应在你的 nuxt.config 中设置。

你可以将此代码放在 Nuxt 或 Nitro 插件或中间件中，而不是从你的 nuxt.config 将不可序列化的对象或函数传递到你的应用程序中。

环境变量

提供配置的最常见方法是使用 环境变量。

Nuxi CLI 内置了在开发、构建和生成中读取你的 .env 文件的支持。但是，当你运行已构建的服务器时，你的 .env 文件将不会被读取。
Read more in Docs > Guide > Directory Structure > Env.

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

有两个关键要求：

  1. 你所需的变量必须在你的 nuxt.config 中定义。这确保了任意环境变量不会暴露给你的应用程序代码。
  2. 只有特殊命名的环境变量才能覆盖运行时配置属性。也就是说，一个以 NUXT_ 开头的大写环境变量，它使用 _ 分隔键和大小写更改。
将 runtimeConfig 值的默认值设置为不同命名的环境变量（例如将 myVar 设置为 process.env.OTHER_VARIABLE）仅在构建时有效，并且在运行时会中断。建议使用与你的 runtimeConfig 对象结构匹配的环境变量。
观看 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: '', // can be overridden by NUXT_API_SECRET environment variable
    public: {
      apiBase: '', // can be overridden by NUXT_PUBLIC_API_BASE environment variable
    }
  },
})

读取

Vue App

在你的 Nuxt 应用程序的 Vue 部分中，你需要调用 useRuntimeConfig() 来访问运行时配置。

客户端和服务器端的行为不同：

  • 在客户端，只有 runtimeConfig.public 和 runtimeConfig.app（Nuxt 内部使用）中的键可用，并且该对象既可写又具有响应性。
  • 在服务器端，整个运行时配置都可用，但它是只读的，以避免上下文共享。
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>Check developer console!</div>
  </div>
</template>
安全提示： 注意不要通过渲染它们或将它们传递给 useState 将运行时配置键暴露给客户端。

插件

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

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(event)
  const result = await $fetch('https://my.api.com/test', {
    headers: {
      Authorization: `Bearer ${apiSecret}`
    }
  })
  return result
})
将 event 作为参数传递给 useRuntimeConfig 是可选的，但建议传递它以获取被 环境变量 在运行时覆盖的服务器路由的运行时配置。

类型化运行时配置

Nuxt 尝试使用 unjs/untyped 从提供的运行时配置自动生成一个 typescript 接口。

但也可以手动键入你的运行时配置：

index.d.ts
declare module 'nuxt/schema' {
  interface RuntimeConfig {
    apiSecret: string
  }
  interface PublicRuntimeConfig {
    apiBase: string
  }
}
// It is always important to ensure you import/export something when augmenting a type
export {}
nuxt/schema 作为一种便利的方式提供给最终用户，以便在他们的项目访问 Nuxt 使用的 schema 版本。模块作者应该改为增强 @nuxt/schema。
在 Nuxt 3 中，nuxt.config.ts、app.config.ts 和 runtimeConfig 都涉及到应用的配置管理，但它们的作用和使用场景有所不同。下面是它们的主要区别：
特性nuxt.config.tsapp.config.tsruntimeConfig
定义时机项目初始化时，配置 Nuxt 构建、路由、模块等项目初始化时，定义 UI 和静态配置运行时，基于环境、用户等动态加载
配置类型全局配置项（插件、构建、模块等）静态 UI 配置（主题、布局、颜色等）运行时配置，支持动态修改和环境差异（如环境变量）
访问方式useNuxtAppConfig()useAppConfig()useRuntimeConfig()
修改方式不支持在运行时动态修改不支持在运行时动态修改支持在运行时动态修改，分为 public 和 private 配置
典型用途配置 Nuxt 模块、插件、构建、路由等配置 UI 相关的静态设置，如主题、颜色、布局等配置运行时相关的数据，如 API 密钥、环境变量等

总结：
  • nuxt.config.ts 是 Nuxt 应用的主要配置文件，定义了全局设置、插件、模块等，通常是构建时静态的配置。
  • app.config.ts 用于存储静态的应用 UI 配置，适合存放不变的 UI 配置项，如主题、颜色等。虽然 app.config.ts 是一个静态配置文件，但通过 updateAppConfig，你可以在运行时灵活地更新其中的配置。
  • runtimeConfig 适用于需要在应用运行时根据环境或其他因素动态变化的配置，支持客户端和服务端的访问，分为 public 和 private 两个部分。