使用 Vue & UI Pro 的仪表板模板

运行时配置

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

const runtimeConfig = useRuntimeConfig()

console.log(runtimeConfig.apiSecret)
console.log(runtimeConfig.public.apiBase)
公共运行时配置可以通过 $config.public 在 Vue 模板中访问。

序列化

您的运行时配置将在传递给 Nitro 之前被序列化。这意味着任何无法序列化然后反序列化(例如函数、集合、映射等)的东西都不应该设置在您的 nuxt.config 中。

与其从您的 nuxt.config 中将不可序列化的对象或函数传递到您的应用程序中,不如将此代码放在 Nuxt 或 Nitro 插件或中间件中。

环境变量

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

Nuxi CLI 在开发、构建和生成时内置支持读取您的 .env 文件。但是,当您运行构建的服务器时,您的 .env 文件将不会被读取
文档 > 指南 > 目录结构 > Env 中了解更多信息。

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

有两个关键要求

  1. 您所需的变量必须在您的 nuxt.config 中定义。这确保了任意环境变量不会暴露给您的应用程序代码。
  2. 只有特殊命名的环境变量才能覆盖运行时配置属性。也就是说,以 NUXT_ 开头的、使用 _ 分隔键并进行大小写转换的大写环境变量。
runtimeConfig 值的默认值设置为不同命名的环境变量(例如,将 myVar 设置为 process.env.OTHER_VARIABLE)仅在构建时有效,在运行时会失效。建议使用与您的 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 应用程序

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

客户端和服务器端的行为不同
  • 在客户端,只有 runtimeConfig.public 中的键可用,并且该对象是可写且可响应的。
  • 在服务器端,整个运行时配置在服务器端可用,但它是只读的,以避免上下文共享。
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 在其项目中使用的模式版本。模块作者应改为扩展 @nuxt/schema