Cloudflare Workers 本機秘密怎麼放：.dev.vars、.env 與 secrets.required 的選擇

先分清楚 vars 與 secret#

vars 適合不敏感的文字或 JSON 設定，例如功能開關。Cloudflare 文件明確提醒不要在 Wrangler 設定檔的 vars 放敏感資料。API key、OAuth client secret 這類值，本機放入未追蹤的 .dev.vars，正式環境再用 wrangler secret put 或 Dashboard 設定。

1
# .dev.vars（加入 .gitignore）
2
API_BASE_URL="http://localhost:8787"
3
UPSTREAM_API_TOKEN="replace-with-local-token"

Worker 端仍從 env 讀取，不需要為本機另寫一條程式路徑：

1
export default {
2
  async fetch(_request: Request, env: Env) {
3
    return Response.json({ endpoint: env.API_BASE_URL });
4
  },
5
};

.dev.vars 與 .env 為什麼不能一起放#

Wrangler 偵測到 .dev.vars 時，不會再把 .env 的值載入 Worker env。這不是覆寫順序，而是兩套來源的選擇；同時維護很容易讓人以為某個值有載到、實際卻仍是 undefined。

若選 .env，可用 .env.local、.env.<environment-name> 與 .env 分層，較具體的檔案優先。若改用 .dev.vars.staging，以 --env staging 啟動時只會使用該環境檔，不會再與預設 .dev.vars 合併。

1
# 用 staging 對應的本機設定啟動
2
pnpm wrangler dev --env staging

用 secrets.required 把漏設變成警告#

若專案只有少數必要秘密，可在 Wrangler 設定宣告名稱。如此本機只載入列出的 key，缺少值時會出現警告，也不會意外把資料夾裡多餘的 dotenv 值交給 Worker。

1
{
2
  "secrets": {
3
    "required": ["UPSTREAM_API_TOKEN"]
4
  }
5
}

這個設定只是在本機建立輸入邊界，不能取代 .gitignore 或正式環境的 secret 管理。提交前用 git status --ignored 確認 .dev.vars 沒有被納入追蹤；部署前則檢查正式 secret 是否已建立。

最小驗證順序#

1. 選擇 .dev.vars 或 .env 其中一種，並加入 .gitignore。
2. 用 pnpm wrangler dev 啟動，讓缺失的必要秘密先在本機被看見。
3. 以不同環境測試時，明確傳入 --env，不要靠終端機殘留的環境變數猜測。
4. 正式部署將秘密改用 wrangler secret put；不要把值搬進 vars。

若還要連接遠端 binding，先看 Cloudflare Workers compatibility_date 升級檢查；它是相容性設定，不能替代本機秘密的隔離。

參考資料：

Cloudflare Workers：Environment variables and secrets

Cloudflare Workers：Local development