核心修練
SecurityDevOps
環境變數
在開發應用程式時，我們經常需要管理 API 金鑰、資料庫連線字串等敏感資訊。Nuxt 提供了 Runtime Config 來安全地管理這些環境變數，並支援在不同環境（開發/生產）中自動切換。
核心概念
Runtime Config 的核心目的是區分私有 (Private) 與公開 (Public) 資訊。 私有變數只能在伺服器端存取，永遠不會洩漏給瀏覽器。
Security Boundary
Server Side
apiSecret
sk_live_...
Private
public.apiBase
/api/v1
Client Side
apiSecret
undefined
public.apiBase
/api/v1
Public
Hydration Boundary
設定變數
在 nuxt.config.ts 中定義。 根層級的屬性為私有，public 物件內的屬性為公開。
nuxt.config.ts
export default defineNuxtConfig({
runtimeConfig: {
// [Private] 僅 Server 可見
// 這裡的值可以設為空字串，等待環境變數覆寫
apiSecret: '',
// [Public] Client & Server 皆可見
public: {
apiBase: '/api',
siteName: 'My Nuxt App'
}
}
}) 讀取變數
使用 useRuntimeConfig() Composable 來存取設定。 Nuxt 會自動為這些變數提供型別支援。
server/api/test.ts
export default defineEventHandler((event) => {
const config = useRuntimeConfig()
// Server 端可以存取所有變數
console.log(config.apiSecret)
console.log(config.public.apiBase)
})app.vue
<script setup>
const config = useRuntimeConfig()
// Client 端只能存取 public 內的變數
console.log(config.public.apiBase)
// ❌ 嘗試存取私有變數會得到 undefined
console.log(config.apiSecret)
</script> 環境變數覆寫
在生產環境中，你不需要修改程式碼。Nuxt 會自動讀取符合 NUXT_ 命名規則的環境變數來覆寫設定。 這對於 CI/CD 部署非常重要。
runtimeConfig.apiSecret
NUXT_API_SECRET
runtimeConfig.public.apiBase
NUXT_PUBLIC_API_BASE
.env
NUXT_API_SECRET=sk_prod_123456789
NUXT_PUBLIC_API_BASE=https://api.production.com實驗室：環境變數覆寫
試著修改左側的環境變數，觀察右側的 Runtime Config 如何即時更新。 注意 apiSecret 在 Client Context 中始終為 undefined。
nuxt.config.tsDefault Values
export default defineNuxtConfig({
runtimeConfig: {
apiSecret: 'default_dev_secret',
public: {
apiBase: '/api/dev'
}
}
})
runtimeConfig: {
apiSecret: 'default_dev_secret',
public: {
apiBase: '/api/dev'
}
}
})
.env / Environment VariablesOverrides Defaults
Server Context
config.apiSecretsk_prod_88888888
config.public.apiBasehttps://api.production.com
Client Context
config.apiSecretundefined
config.public.apiBasehttps://api.production.com
Runtime vs App Config
Nuxt 還有另一個設定檔 app.config.ts。它們有什麼不同？
Runtime Config
- 私有/敏感資訊 (API Keys)
- 需要環境變數覆寫 (Build vs Runtime)
- 在 Build 之後仍可改變
App Config
- 公開資訊 (UI Theme, Title)
- 不需要環境變數覆寫
- 在 Build 時就決定了 (Bundled)