執行時配置

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)
公共執行時配置可在 Vue 模板中使用 $config.public 訪問。

序列化

您的執行時配置在傳遞給 Nitro 之前將被序列化。這意味著任何不能被序列化然後反序列化的內容（例如函式、Set、Map 等）都不應在您的 nuxt.config 中設定。

您可以將這些不可序列化的物件或函式放置在 Nuxt 或 Nitro 外掛或中介軟體中，而不是從 nuxt.config 中傳遞到您的應用程式。

環境變數

提供配置最常見的方式是使用環境變數.

Nuxt CLI 在開發、構建和生成過程中內建支援讀取您的 .env 檔案。但是當您執行已構建的伺服器時，您的 .env 檔案將不會被讀取。
請參閱 文件 > 4 X > 指南 > 目錄結構 > 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.tw
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 和 runtimeConfig.app（Nuxt 內部使用）中的鍵可用，並且該物件是可寫和響應式的。
  • 在伺服器端，整個執行時配置都可用，但它是隻讀的，以避免上下文共享。
app/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()。

app/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 嘗試使用以下工具自動從提供的執行時配置生成 TypeScript 介面unjs/untyped.

但也可以手動為您的執行時配置新增型別

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。