測驗：Vercel 環境變數設定
共 5 題，點選答案後會立即顯示結果
1. 為什麼不應該把 API Key 直接寫在程式碼裡？
2. 在 Vercel Dashboard 中，環境變數設定位於哪個位置？
3. Vercel 的 Preview 環境會在什麼時機觸發？
4. 在 Next.js 專案中，以下哪個環境變數命名方式會讓變數暴露給瀏覽器？
5. 在 Vercel Dashboard 修改環境變數後，需要做什麼才能讓變更生效？
為什麼需要環境變數？
當你開發一個需要呼叫外部 API 的專案時，通常會拿到一組 API Key。很多新手會直接把 API Key 寫在程式碼裡：
// 千萬不要這樣做！
const apiKey = "sk-1234567890abcdef";
Code language: JavaScript (javascript)這樣做有什麼問題？
- 安全風險：程式碼推上 GitHub 後，任何人都能看到你的 API Key
- 帳單爆炸：惡意人士可以用你的 Key 大量呼叫 API，讓你收到天價帳單
- 無法區分環境：開發時想用測試 Key，上線後想用正式 Key，寫死就無法切換
環境變數的作用就是把這些敏感資訊從程式碼中抽離，讓程式「讀取環境中的設定值」，而不是「寫死在程式碼裡」。
在 Vercel Dashboard 設定環境變數
找到設定位置
- 登入 Vercel Dashboard
- 點選你的專案
- 點選上方的 Settings 頁籤
- 在左側選單找到 Environment Variables
你會看到一個設定介面，包含三個欄位：
- Key：變數名稱（例如
OPENAIAPIKEY） - Value：變數值（你的 API Key）
- Environment：要套用到哪些環境
實際操作範例
假設你要設定 OpenAI 的 API Key：
Key: OPENAI_API_KEY
Value: sk-proj-xxxxxx（你的實際 Key）
Code language: HTTP (http)輸入完成後，點選 Save 儲存。
三種環境的差異
Vercel 把部署分成三種環境，每種環境可以有不同的環境變數值：
| 環境 | 說明 | 觸發時機 |
|---|---|---|
| Production | 正式環境 | 合併到主分支（main/master） |
| Preview | 預覽環境 | 開 Pull Request 或推送到其他分支 |
| Development | 開發環境 | 本地執行 vercel dev |
為什麼要區分環境？
看這個實際情境：
Production 環境：使用正式的 OpenAI API Key（有付費額度）
Preview 環境：使用測試用的 API Key（額度較低）
Development 環境：使用本地開發用的 Key
這樣的好處是：
- 開發時不怕用光正式環境的額度
- PR 預覽也不會影響正式環境的資料
- 出問題時可以快速定位是哪個環境
設定時勾選環境
在 Vercel Dashboard 設定環境變數時，你會看到三個勾選框：
[ ] Production
[ ] Preview
[ ] Development
Code language: CSS (css)根據你的需求勾選。大多數情況下，會把三個都勾起來使用同一個值。但如果你有不同環境要用不同值的需求，可以分別設定。
在程式碼中使用環境變數
設定好環境變數後，要怎麼在程式碼中使用呢？
Node.js / Next.js 專案
// 讀取環境變數
const apiKey = process.env.OPENAI_API_KEY;
// 使用環境變數
const response = await fetch("https://api.openai.com/v1/chat/completions", {
headers: {
"Authorization": `Bearer ${apiKey}`,
"Content-Type": "application/json"
},
// ...
});
Code language: JavaScript (javascript)Next.js 的特殊規則
Next.js 有一個重要的命名規則：
| 前綴 | 可用位置 | 安全性 |
|---|---|---|
NEXT_PUBLIC_ |
前端 + 後端都可用 | 會暴露給瀏覽器 |
| 無前綴 | 只有後端（API Routes、Server Components） | 安全，不會暴露 |
// 這個會暴露給瀏覽器，任何人都看得到
const publicKey = process.env.NEXT_PUBLIC_ANALYTICS_ID;
// 這個只有伺服器端能存取，比較安全
const secretKey = process.env.DATABASE_PASSWORD;
Code language: JavaScript (javascript)重要原則：API Key 這種敏感資料，絕對不要加 NEXT_PUBLIC_ 前綴！
常見錯誤與除錯技巧
錯誤 1：環境變數是 undefined
console.log(process.env.MY_API_KEY); // undefined
Code language: JavaScript (javascript)檢查清單：
- 變數名稱有沒有打錯？（大小寫敏感）
- 有沒有在 Vercel Dashboard 設定？
- 設定後有沒有重新部署？（環境變數修改後需要重新部署才會生效）
錯誤 2：本地開發時讀不到
Vercel 上設定的環境變數，本地開發時預設讀不到。解決方法：
方法一：使用 Vercel CLI
vercel env pull .env.local
Code language: CSS (css)這會把 Vercel 上的 Development 環境變數下載到本地的 .env.local 檔案。
方法二：手動建立 .env.local
# .env.local
OPENAI_API_KEY=sk-proj-xxxxxx
Code language: PHP (php)重要：記得把 .env.local 加入 .gitignore，不要推上 GitHub！
錯誤 3：前端讀不到環境變數
如果你在瀏覽器的 JavaScript 中讀不到環境變數：
// 在瀏覽器中執行
console.log(process.env.MY_SECRET); // undefined（這是正確的！）
Code language: JavaScript (javascript)這是 Next.js 的安全機制。沒有 NEXT_PUBLIC_ 前綴的變數，刻意不讓前端存取。
解決方法：如果這個變數真的需要在前端使用，加上 NEXT_PUBLIC_ 前綴。但請再三確認這個資料是否適合公開。
錯誤 4：修改環境變數後沒有生效
環境變數的修改需要重新部署才會套用。你可以：
- 手動觸發重新部署：在 Vercel Dashboard 的 Deployments 頁面點選 Redeploy
- 推送新的 commit：任何程式碼變更都會觸發重新部署
實際應用情境
情境：設定資料庫連線字串
Key: DATABASE_URL
Value: postgresql://user:password@host:5432/dbname
Environment: 全部勾選
Code language: HTTP (http)程式碼中使用：
import { PrismaClient } from '@prisma/client';
const prisma = new PrismaClient({
datasources: {
db: {
url: process.env.DATABASE_URL,
},
},
});
Code language: JavaScript (javascript)情境：不同環境使用不同的 API 端點
Production 環境：
Key: API_ENDPOINT
Value: https://api.example.com
Code language: HTTP (http)Preview 環境：
Key: API_ENDPOINT
Value: https://staging-api.example.com
Code language: HTTP (http)程式碼中使用：
const endpoint = process.env.API_ENDPOINT;
const response = await fetch(`${endpoint}/users`);
Code language: JavaScript (javascript)小結
環境變數是保護敏感資料的基本功。記住這幾個重點：
- 永遠不要把 API Key 寫在程式碼裡
- 在 Vercel Dashboard 的 Settings > Environment Variables 設定
- 區分 Production、Preview、Development 三種環境
- Next.js 專案中，敏感資料不要加 NEXTPUBLIC 前綴
- 修改環境變數後需要重新部署
下一篇我們會介紹如何設定自訂網域，讓你的網站擁有專屬的網址。
進階測驗：Vercel 環境變數設定
測驗目標：驗證你是否能在實際情境中應用所學。
共 5 題，包含情境題與錯誤診斷題。
共 5 題，包含情境題與錯誤診斷題。
1. 你正在開發一個需要呼叫 OpenAI API 的 Next.js 專案，需要在程式碼中使用 API Key。你應該怎麼做？ 情境題
2. 小明的程式碼在本地執行時正常，但部署到 Vercel 後出現以下錯誤。最可能的原因是什麼？ 錯誤診斷
console.log(process.env.MY_API_KEY);
// 輸出：undefined
3. 你的團隊想要在 Preview 環境使用測試用的 API（額度較低），Production 環境使用正式 API。應該如何設定？ 情境題
4. 小華在瀏覽器的開發者工具 Console 中執行以下程式碼，結果是 undefined。她的專案是 Next.js，這個行為正確嗎？ 錯誤診斷
// 在瀏覽器中執行
console.log(process.env.DATABASE_PASSWORD);
// 輸出：undefined