1 核心概念
Nuxt 的設定檔將變數分為兩類：
Private Keys (私密金鑰)
- •定義位置：
runtimeConfig的第一層。 - •可見範圍：只在伺服器端 (Server) 可見。
- •用途：資料庫密碼、OpenAI API Key。
- •安全機制：如果在瀏覽器端 (Client) 嘗試讀取，會得到
undefined。
Public Keys (公開變數)
- •定義位置：
runtimeConfig.public裡面。 - •可見範圍：伺服器與瀏覽器皆可見。
- •用途：API 基礎網址 (Base URL)、Google Analytics ID、網站名稱。
2 給 Claude Code 的中文指令 可複製
我們要模擬一個情境：設定一個「絕對機密的 API Token」和一個「公開的 API 網址」，並觀察它們在不同地方的行為。
請幫我設定 Nuxt 的環境變數管理：
- 在根目錄建立
.env檔案，寫入兩行內容：NUXT_API_SECRET=my_super_secret_token_123NUXT_PUBLIC_API_BASE=https://api.example.com
- 修改
nuxt.config.ts中的 runtimeConfig：- 新增
apiSecret(對應 NUXT_API_SECRET，預設值為空字串)。 - 新增
public物件，裡面包含apiBase(對應 NUXT_PUBLIC_API_BASE，預設值為空字串)。
- 新增
- 建立一個測試頁面
app/pages/config-test.vue：- 在
<script setup>中使用useRuntimeConfig()取得設定。 - 在
console.log印出apiSecret和public.apiBase。 - 在 template 中嘗試顯示這兩個變數，看看誰顯示得出來。
- 在
3 驗收重點
這是一個關於「安全性」的驗收，請仔細觀察：
瀏覽器端檢查 (Client Side)
- 打開瀏覽器
http://localhost:3000/config-test。 - 按
F12打開 Console。 - 你會看到
public.apiBase印出了網址。 - 關鍵點：你會發現
apiSecret印出undefined(或是空字串)。 - 畫面上的 Template 也應該只顯示得出 Public 的變數。
結論：成功！私密金鑰沒有洩漏給瀏覽器。
伺服器端檢查 (Server Side)
- 看你的 VS Code 終端機 (Terminal)。
- 重新整理網頁（觸發 SSR）。
- 你會在終端機看到
my_super_secret_token_123被印出來了。
結論：成功！伺服器端讀得到這把鑰匙（可以用來呼叫後端 API）。
💡 架構師筆記 (環境變數命名法)
Nuxt 有個很聰明的自動對應功能。你在 nuxt.config.ts 定義了 apiSecret (駝峰式)，Nuxt 會自動去環境變數找 NUXT_API_SECRET (大寫底線)。
Config: apiSecret → Env: NUXT_API_SECRET
Config: public.apiBase → Env: NUXT_PUBLIC_API_BASE
部署優勢：這意味著在生產環境（如 Vercel, Netlify, Docker）部署時，你不需要改 code，只要在後台設定環境變數，Nuxt 就會自動抓取。