v3.17
GitHub

运行时配置

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 之前，您的运行时配置将被序列化。这意味着任何无法被序列化和随后反序列化的内容（例如函数、集合、映射等），都不应该在您的 nuxt.config 中设置。

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

环境变量

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

Nuxt 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: '', // 可以被 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
})
将 event 作为参数传递给 useRuntimeConfig 是可选的，但建议传递它，以便在运行时为服务器路由获取被环境变量 /docs/guide/going-further/runtime-config#environment-variables 覆盖的运行时配置。

类型定义运行时配置

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。