运行时配置

暴露

¥Exposing

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

¥To expose config and environment variables to the rest of your app, you will need to define runtime configuration in your nuxt.config file, using the runtimeConfig option.

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 会将其添加到每个页面的有效负载中。我们可以在服务器和浏览器中通用访问 apiBase。

¥When adding apiBase to the runtimeConfig.public, Nuxt adds it to each page payload. We can universally access apiBase in both server and browser.

const runtimeConfig = useRuntimeConfig()

console.log(runtimeConfig.apiSecret)
console.log(runtimeConfig.public.apiBase)

序列化

¥Serialization

你的运行时配置将在传递给 Nitro 之前进行序列化。这意味着任何无法序列化和反序列化的内容（例如函数、Set、Map 等）都不应在 nuxt.config 中设置。

¥Your runtime config will be serialized before being passed to Nitro. This means that anything that cannot be serialized and then deserialized (such as functions, Sets, Maps, and so on), should not be set in your nuxt.config.

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

¥Instead of passing non-serializable objects or functions into your application from your nuxt.config, you can place this code in a Nuxt or Nitro plugin or middleware.

环境变量

¥Environment Variables

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

¥The most common way to provide configuration is by using Environment Variables.

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

¥Runtime config values are automatically replaced by matching environment variables at runtime.

有两个关键要求：

¥There are two key requirements:

1. 你所需的变量必须在 nuxt.config 中定义。这确保了任意环境变量不会暴露给你的应用代码。
2. 只有特殊命名的环境变量才能覆盖运行时配置属性。也就是说，一个以 NUXT_ 开头的大写环境变量，使用 _ 分隔键和大小写变化。

示例

¥Example

NUXT_API_SECRET=api_secret_token
NUXT_PUBLIC_API_BASE=https://nuxtjs.org

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
    }
  },
})

阅读

¥Reading

Vue 应用

¥Vue App

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

¥Within the Vue part of your Nuxt app, you will need to call useRuntimeConfig() to access the runtime config.

<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>

插件

¥Plugins

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

¥If you want to use the runtime config within any (custom) plugin, you can use useRuntimeConfig() inside of your defineNuxtPlugin function.

export default defineNuxtPlugin((nuxtApp) => {
  const config = useRuntimeConfig()

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

服务器路由

¥Server Routes

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

¥You can access runtime config within the server routes as well using useRuntimeConfig.

export default defineEventHandler(async (event) => {
  const { apiSecret } = useRuntimeConfig(event)
  const result = await $fetch('https://my.api.com/test', {
    headers: {
      Authorization: `Bearer ${apiSecret}`
    }
  })
  return result
})

Typing 运行时配置

¥Typing Runtime Config

Nuxt 会尝试使用 unjs/untyped 根据提供的运行时配置自动生成 TypeScript 接口。

¥Nuxt tries to automatically generate a typescript interface from provided runtime config using unjs/untyped.

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

¥But it is also possible to type your runtime config manually:

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 {}