运行时配置

Nuxt 提供了运行时配置 API,用于在应用程序中公开配置和机密信息。

公开配置

要将配置和环境变量公开给应用的其他部分,您需要在 nuxt.config 文件中使用 runtimeConfig 选项定义运行时配置。

nuxt.config.ts
export default defineNuxtConfig({
  runtimeConfig: {
    // 仅在服务器端可用的私有键
    apiSecret: '123',
    // 公开的键也会暴露给客户端
    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 或 Nitro 插件或中间件中。

环境变量

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

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.publicruntimeConfig.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
})
useRuntimeConfig 传入 event 参数是可选的,但建议传入,以便服务器路由的运行时配置能被环境变量正确覆盖。

运行时配置的类型定义

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