第 2 週 · API 設計與接上前端
環境變數與 wrangler secret
公開的設定放 vars，機密放 secret，本機用 .dev.vars，而且不要提交到 Git。
正在打開這一關…
學習目標
- 分得清環境變數與秘密
- 在程式裡用 env 讀到它們
- 會用 wrangler secret put，也知道它會立刻佈署一版
昨天的允許來源寫在 wrangler.jsonc 的 vars。那是非機密。金鑰、簽章用的胡椒、第三方權杖，都不能寫進 Git。Wrangler 用 secret 放這些值。本機開發則讀 .dev.vars。
用生活例子理解
- 環境變數像貼在員工布告欄的營業時間。大家看得到，換門市可以換一張。
- 秘密像保險櫃密碼。設定檔只寫「我們有一把鑰匙叫
PEPPER」，不寫密碼本身。 - 程式裡兩邊都從
env.名字讀。差別是秘密怎麼送進平台，不是程式裡的讀法。
生活比喻：食譜可以寫「加一茶匙秘密香料」。香料罐放在保險櫃。你不會把罐子拍照上傳到公開的食譜庫。
本機檔案 .dev.vars 用 dotenv 格式：
PEPPER="only-for-local-dev"這個檔案要列在 .gitignore。可以提交 .dev.vars.example，裡面只放假字。
若專案同時有 .dev.vars 與 .env，Wrangler 只用 .dev.vars。本課固定用 .dev.vars。
放到網路上的秘密用：
npx wrangler secret put PEPPER指令會請你輸入值，不要把值寫在指令後面，那樣會留在終端機歷史。secret put 會做出新版本並立刻佈署。若你正在用逐步佈署，改用文件裡的 wrangler versions secret put，先上傳版本再決定何時切換。學習階段用 secret put 前，先確認你真的想更新線上那一版。
動手做
大約 20 分鐘。
- 在 Worker 專案新增
.dev.vars，寫入PEPPER="please-change-me"。 - 確認
.gitignore有.dev.vars。 - 用案例的程式，在
GET /api/health只回「有沒有設定」，不要把秘密本身回傳。 npx wrangler dev，打開/api/health。應看到{ "pepper": true }。- 把
.dev.vars改名藏起來再跑一次，應變成false。改回來。 - 在設定檔加上非機密
vars.ALLOWED_ORIGIN。重新啟動後，env.ALLOWED_ORIGIN應讀得到。秘密與vars可以同時存在。
先不要對真實帳號執行 secret put，除非你已經有要佈署的 Worker。知道指令與副作用即可。
案例
{
"$schema": "./node_modules/wrangler/config-schema.json",
"name": "guestbook-env",
"main": "src/index.js",
"compatibility_date": "2026-10-30",
"vars": {
"ALLOWED_ORIGIN": "http://localhost:3000"
}
}export default {
async fetch(request, env) {
const url = new URL(request.url);
if (url.pathname !== "/api/health") {
return Response.json({ error: "找不到" }, { status: 404 });
}
// 只回答有沒有設定。絕對不要把 env.PEPPER 放進回應或紀錄。
return Response.json({
allowedOrigin: env.ALLOWED_ORIGIN ?? null,
pepper: Boolean(env.PEPPER),
});
},
};可以在設定裡宣告必要秘密的名字，佈署時若沒設定就失敗，避免帶著空鑰匙上線：
{
"secrets": {
"required": ["PEPPER"]
}
}名字可以公開，值不行。
常見錯誤
- 把金鑰寫在
vars或前端的 JavaScript。倉庫一公開就洩漏，而且前端的值客人看得到。 - 為了除錯
console.log(env.PEPPER)。紀錄也會被看到。 - 提交
.dev.vars。即使是練習用的假密碼，養成習慣比事後清理歷史簡單。 - 以為改了
.dev.vars就更新了線上環境。本機檔只影響本機。線上要另外secret put。
自我檢查
- 允許的網址與
PEPPER各該放哪裡？ - 為什麼健康檢查只回布林值，不回秘密內容？
wrangler secret put除了存值，還會做什麼？