wrangler.jsonc 設定完整解析:必填欄位、bindings 與 observability | Cloudflare 完整教學

上一篇我們用 wrangler deploy 把 Worker 送上了邊緣,但那份決定 Worker 名稱、入口、綁定與相容性的 wrangler.jsonc,我們只匆匆帶過。這一篇,我們把這份設定檔從頭到尾徹底拆開——先講清楚 name、main、compatibility_date、compatibility_flags 四大核心欄位,再逐一示範 KV、R2、D1、Durable Objects、Queues、AI、vars 各種 binding 的宣告語法,接著帶你設定 routes、workers.dev、observability、assets、triggers、limits,最後比較 JSONC 與 TOML 的差異。讀完你就能隨心所欲地設定自己的 Worker。

前言

上一篇《Wrangler 入門》,我們認識了 Cloudflare 官方 CLI——Wrangler,走過了安裝、login、用 C3 建專案、wrangler dev 本地開發到 wrangler deploy 一鍵部署的完整流程。但整趟旅程裡,有一個檔案一直站在幕後默默指揮全局,我們卻始終沒有正眼看它——那就是 wrangler.jsonc。

先給一句話定義:wrangler.jsonc 是 Cloudflare Workers 專案的設定檔,採用 JSONC(JSON with Comments,可寫註解的 JSON)格式。它以宣告式的方式描述你的 Worker「叫什麼名字、入口在哪、跑在哪個 runtime 版本、要綁定哪些資源、部署到哪些網址、開不開觀測」——Wrangler 在 dev 與 deploy 時都讀取這份檔案,把你的意圖翻譯成實際的執行環境。

打個比方:如果 Worker 是一台要出海的貨輪,那 wrangler.jsonc 就是這艘船的艙單與航行計畫書——它記載了船名(name)、引擎起點(main)、適用的航海規章版本(compatibility_date)、船上載了哪些貨櫃(各種 binding),以及要停靠哪些港口(routes)。Wrangler 這位船長不會憑感覺開船,而是嚴格照著這份計畫書執行。計畫書寫錯一個字,船就可能靠錯港、卸錯貨。

正因為它是「宣告式」的——你只描述要什麼,而非寫程式去建立——所以理解每個欄位的意義與正確寫法,就成了穩定部署的關鍵。讀完本篇,你會掌握:

• 四大核心欄位——name、main、compatibility_date、compatibility_flags 各自的意義、限制與正確設法
• 各種 binding 宣告——KV、R2、D1、Durable Objects、Queues、AI、vars 的完整語法與常見選項
• 路由與觀測——routes vs workers.dev、observability、assets、triggers、limits 怎麼設
• 格式選擇——為什麼 JSONC 取代了舊版 TOML,以及 $schema 帶來的 IDE 好處

核心概念

wrangler.jsonc 主要欄位對照表

在動手前,先建立一張全局地圖。wrangler.jsonc 的欄位大致可分成四類:身份與相容性、資源綁定、路由與觸發、行為與觀測。以下是最常用欄位的速查表(細節後面逐一展開):

註:main 標「是*」是因為——若你的專案是「純靜態資源」(assets-only,沒有任何 Worker 程式碼),main 可以省略;只要有一行 Worker 邏輯,main 就是必填。

運作原理:宣告式設定如何變成執行環境

理解 wrangler.jsonc 的關鍵,是抓住它的宣告式(declarative)本質。你不是在寫「先建立一個 KV,再把它接到 Worker」這種步驟;你只是描述「我這個 Worker 有一個叫 CACHE 的 KV 綁定,它指向 ID 為 xxx 的 namespace」。真正的接線工作,Wrangler 幫你完成:

• 本地 dev 時:Wrangler 讀設定,用 Miniflare 在本機模擬這些綁定(KV、R2、D1 在 .wrangler/state/ 建本地版本),讓 env.CACHE 在你的程式裡「憑空」可用。
• deploy 時:Wrangler 把設定裡宣告的每個綁定,連同打包好的程式碼一起上傳,告訴 Cloudflare 邊緣「這個 Worker 需要存取這些真實資源」,於是線上的 env.CACHE 就連到真正的 KV namespace。

這條「設定 → env 物件」的對應,是所有 binding 的核心心智模型:設定檔裡的 binding 欄位值,就是程式碼裡 env 物件上的屬性名稱。 抓住這一點,後面所有綁定的寫法你都能一眼看懂。

關鍵術語

• binding(綁定):把外部資源(KV、R2、D1…)以宣告方式「注入」進 Worker 的機制。每個綁定都有一個 binding(或 name)欄位,決定它在 env 上叫什麼。
• compatibility_date:一個日期字串(yyyy-mm-dd),把 Worker 的 runtime 行為凍結在該日,避免未來的破壞性變更影響你。
• compatibility_flags:相容性旗標陣列,用來個別開啟或關閉某些 runtime 功能(例如 nodejs_compat 開啟 Node.js API 相容),比日期更細粒度。
• $schema:設定檔頂端指向 Wrangler JSON schema 的欄位,讓 VS Code 等編輯器提供自動完成與即時錯誤檢查——這是 JSONC 相較 TOML 的一大優勢。

實作範例

概念齊了,我們直接看一份涵蓋多數常用功能、逐段附上中文註解的完整 wrangler.jsonc,再拆開講解每一區塊。

一份完整的 wrangler.jsonc

{
  // $schema:指向 Wrangler 的設定 schema,讓編輯器提供自動完成與即時驗證
  "$schema": "node_modules/wrangler/config-schema.json",

  // ── 核心欄位 ──
  "name": "my-api-worker",              // Worker 名稱:kebab-case,最長 255 字元
  "main": "src/index.ts",               // 入口檔案:Worker 程式碼的進入點
  "compatibility_date": "2026-08-07",   // 相容性日期:凍結 runtime 行為(必填)
  "compatibility_flags": ["nodejs_compat"], // 開啟 Node.js API 相容

  // ── 路由 ──
  "workers_dev": false,                 // 關閉 *.workers.dev 子網域(改用自訂網域)
  "routes": [
    {
      "pattern": "api.example.com/*",   // 路由樣式
      "zone_name": "example.com"        // 這個網域所屬的 Cloudflare Zone
    }
  ],

  // ── 環境變數(非敏感,明文儲存) ──
  "vars": {
    "ENVIRONMENT": "production",
    "LOG_LEVEL": "info"
  },

  // ── KV 綁定:程式中用 env.CACHE 存取 ──
  "kv_namespaces": [
    { "binding": "CACHE", "id": "<KV_NAMESPACE_ID>" }
  ],

  // ── R2 物件儲存綁定:程式中用 env.UPLOADS 存取 ──
  "r2_buckets": [
    { "binding": "UPLOADS", "bucket_name": "my-uploads" }
  ],

  // ── D1 SQL 資料庫綁定:程式中用 env.DB 存取 ──
  "d1_databases": [
    {
      "binding": "DB",
      "database_name": "my-db",
      "database_id": "<D1_DATABASE_ID>",
      "migrations_dir": "./migrations"  // migration 檔案目錄
    }
  ],

  // ── Workers AI 綁定:程式中用 env.AI 存取(永遠遠端執行) ──
  "ai": { "binding": "AI" },

  // ── Cron 觸發器:定時執行 scheduled handler ──
  "triggers": {
    "crons": ["0 2 * * *"]              // 每天凌晨 2 點
  },

  // ── 觀測:啟用內建 Observability 儀表板 ──
  "observability": {
    "enabled": true,
    "head_sampling_rate": 1             // 1 = 100% 採樣
  },

  // ── 效能限制 ──
  "limits": {
    "cpu_ms": 100                       // 每次請求最大 CPU 時間(毫秒)
  }
}

這份設定看起來很長,但每一區塊各司其職。下面我們一區一區拆開講。

核心欄位:name / main / compatibility_date / compatibility_flags

這四個是每個 Worker 的地基。

{
  "name": "my-api-worker",
  "main": "src/index.ts",
  "compatibility_date": "2026-08-07",
  "compatibility_flags": ["nodejs_compat"]
}

• name:Worker 的名稱,只允許英數字元與連字號(kebab-case),最長 255 字元。注意——如果你要用 *.workers.dev 子網域對外,名稱會成為子網域的一部分,此時限制更嚴:最長 63 字元,且不可有前後連字號。
• main:Worker 的入口檔案,Wrangler 從這裡開始打包。TypeScript 專案通常指向 src/index.ts。
• compatibility_date:格式 yyyy-mm-dd,把 Worker 的 runtime 行為凍結在這一天。它是必填,而且是理解 Workers 穩定性的關鍵——設好之後,即使 Cloudflare 未來改了 runtime 預設行為,你的 Worker 也不受影響,除非你主動把日期往前推。
• compatibility_flags:相容性旗標陣列,提供比日期更細粒度的開關。最常見的就是 nodejs_compat——當你的程式碼(或相依套件)需要 Node.js 內建 API(如 node:crypto、node:buffer)時,必須加上它。

vars:非敏感環境變數

vars 用來放非敏感的設定值,它們以明文儲存在設定檔中(所以絕不要放 API Key、密碼——那些要用 Secrets):

{
  "vars": {
    "ENVIRONMENT": "production",
    "API_BASE_URL": "https://api.example.com",
    // 值也可以是巢狀 JSON 物件
    "FEATURE_CONFIG": {
      "timeout": 30,
      "retries": 3
    }
  }
}

程式中用 env.ENVIRONMENT、env.FEATURE_CONFIG.timeout 存取。

KV / R2 / D1 綁定

這三種是最常用的儲存綁定。留意每一種的 binding 欄位——它就是 env 上的屬性名:

{
  // KV:鍵值儲存,適合快取、設定
  "kv_namespaces": [
    {
      "binding": "CACHE",           // → env.CACHE
      "id": "<KV_NAMESPACE_ID>",    // 生產環境 namespace ID
      "preview_id": "<PREVIEW_ID>"  // (可選)remote 開發用
    }
  ],

  // R2:S3 相容物件儲存,適合檔案、圖片
  "r2_buckets": [
    {
      "binding": "ASSETS",              // → env.ASSETS
      "bucket_name": "my-assets-bucket",
      "remote": true                    // (可選)本地開發直連真實 bucket
    }
  ],

  // D1:SQLite 為底的 SQL 資料庫
  "d1_databases": [
    {
      "binding": "DB",                  // → env.DB
      "database_name": "my-database",
      "database_id": "<DATABASE_ID>",
      "migrations_dir": "./migrations"  // (可選)migration 目錄
    }
  ]
}

小訣竅:若省略 KV 的 id(或 D1 的 database_id),在支援自動佈建(Auto-Provisioning)的版本中,Wrangler 會在第一次 dev 或 deploy 時自動建立該資源,省去手動建立的步驟。

Durable Objects 綁定

Durable Objects(DO)的綁定結構跟前面幾種不太一樣——它綁的是一個類別(class),而非既有資源 ID:

{
  "durable_objects": {
    "bindings": [
      {
        "name": "COUNTER",        // → env.COUNTER
        "class_name": "Counter"   // 對應程式中 export 的 DO 類別
      }
    ]
  }
}

class_name 必須對應你程式碼裡實際 export 的 Durable Object 類別。首次建立新的 DO 類別時,通常還需搭配 migration(或新版的宣告式 exports)來告訴 Cloudflare「這是一個全新的 DO 類別」。

Queues 綁定(生產者與消費者)

Queues 的設定分成兩半:producers(發送訊息的 Worker)與 consumers(接收處理訊息的 Worker):

{
  "queues": {
    // 生產者:向佇列發送訊息,程式中用 env.MY_QUEUE.send(...)
    "producers": [
      { "binding": "MY_QUEUE", "queue": "my-queue-name" }
    ],
    // 消費者:接收並批次處理訊息
    "consumers": [
      {
        "queue": "my-queue-name",
        "max_batch_size": 10,        // 每批最多 10 則訊息
        "max_batch_timeout": 30,     // 最多等 30 秒湊一批
        "max_retries": 3,            // 失敗最多重試 3 次
        "dead_letter_queue": "dlq"   // 重試耗盡後轉送到死信佇列
      }
    ]
  }
}

AI 綁定

Workers AI 的綁定最簡單——一個專案只能有一個 ai 綁定:

{
  "ai": { "binding": "AI" }  // → env.AI.run(...)
}

特別注意:Workers AI 永遠在遠端執行,本地無法模擬,所以即使 wrangler dev 在本機跑,AI 呼叫仍會連到 Cloudflare 並可能計費——這一點在開發時要留意。

routes、workers.dev 與觸發器

決定「使用者從哪個網址存取你的 Worker」的是 routes 與 workers_dev:

{
  // 預設 true:Worker 會有一個 https://<name>.<帳號>.workers.dev 網址
  // 上生產環境用自訂網域時,通常設成 false
  "workers_dev": false,

  "routes": [
    {
      "pattern": "api.example.com/*",   // 這個路徑走這個 Worker
      "zone_name": "example.com"
    },
    {
      "pattern": "app.example.com",     // 自訂網域(Custom Domain)不用 /*
      "zone_name": "example.com",
      "custom_domain": true             // 會自動建立 DNS 記錄
    }
  ],

  // Cron 觸發器:定時執行 scheduled() handler
  "triggers": {
    "crons": [
      "*/5 * * * *",   // 每 5 分鐘
      "0 9 * * 1-5"    // 週一至週五早上 9 點
    ]
  }
}

關於 triggers 有個容易忽略的細節:若要停用所有 Cron,要把 crons 設成空陣列 [];直接刪掉整個 triggers 欄位是無效的(Cloudflare 會保留舊設定)。

assets 與 observability

assets 讓 Worker 直接服務靜態檔案(SPA、圖片等);observability 則開啟內建的請求/錯誤儀表板:

{
  "assets": {
    "directory": "./dist",                            // 靜態資源目錄
    "binding": "ASSETS",                              // (可選)程式中存取資源
    "not_found_handling": "single-page-application",  // SPA 路由 fallback
    "run_worker_first": ["/api/*"]                    // 這些路徑先過 Worker
  },

  "observability": {
    "enabled": true,
    "head_sampling_rate": 1  // 0~1;1 表示 100% 採樣,量大時可調低省費用
  }
}

啟用 observability 後,可在 Cloudflare Dashboard 直接看到請求量、錯誤率、CPU 時間分布與 P50/P99 延遲,不必自己接第三方監控就有基本可觀測性。

limits:資源限制

limits 用來設定 Worker 的執行上限,最常用的是 cpu_ms:

{
  "limits": {
    "cpu_ms": 50  // 每次請求最多 50 毫秒 CPU 時間(上限 300000)
  }
}

適當設定 cpu_ms 可以在程式意外進入耗時運算(如無窮迴圈)時,提早中止並避免帳單失控。

JSONC vs TOML:為什麼是 .jsonc

你在較舊的教學或專案裡,可能看過的是 wrangler.toml 而非 wrangler.jsonc。這兩者是同一份設定的兩種檔案格式,Wrangler 兩種都讀得懂,但官方已把 JSONC 訂為推薦與預設格式,新版 C3 建立專案時一律生成 .jsonc。理解兩者差異,能幫你判斷該用哪個、以及要不要遷移舊專案。

先看同一段「D1 綁定」在兩種格式下的樣子。TOML 版本:

# wrangler.toml —— 舊格式
name = "my-worker"
main = "src/index.ts"
compatibility_date = "2026-08-07"

[[d1_databases]]
binding = "DB"
database_name = "my-db"
database_id = "<D1_ID>"

JSONC 版本:

// wrangler.jsonc —— 推薦格式
{
  "name": "my-worker",
  "main": "src/index.ts",
  "compatibility_date": "2026-08-07",
  "d1_databases": [
    { "binding": "DB", "database_name": "my-db", "database_id": "<D1_ID>" }
  ]
}

單看這個簡單例子,TOML 甚至更精簡。但一旦設定變複雜——例如 durable_objects.bindings、queues.consumers 這種多層巢狀結構——TOML 的 [[section]] 陣列表頭與縮排就很容易對齊錯亂、難以一眼看懂層級關係;JSONC 的大括號與方括號則清楚標示了每一層的邊界。更重要的是,JSONC 是標準 JSON 再加上「可寫 // 註解」的能力,能直接搭配頂端的 $schema 欄位,讓 VS Code 等編輯器提供自動完成與即時錯誤檢查——打錯欄位名、少寫必填欄位,存檔前就會被標紅。這對複雜設定的維護體驗提升極大。

結論很簡單:新專案一律用 wrangler.jsonc。 既有的 wrangler.toml 專案不會壞、可以繼續跑,但若要新增複雜綁定或想要 IDE 補全,建議找時間轉成 JSONC(欄位名稱幾乎一一對應,轉換不難)。切記:一個專案只放一份設定檔,不要同時擺 .jsonc 和 .toml。

驗證你的設定:dry-run

寫完設定,不必真的部署就能驗證語法與綁定是否正確:

# 打包並驗證設定,但不實際上線
npx wrangler deploy --dry-run

# 改動 binding 後,重新生成 TypeScript 型別
npx wrangler types

--dry-run 是每次改設定後的好習慣;wrangler types 則確保 env 的型別定義與最新設定同步。

常見錯誤與最佳實踐

坑一:compatibility_date 亂設或設成未來日期。

有人為了「用最新功能」把日期設成很未來、或每次部署都往前跳到今天,結果踩到還沒驗證過的行為變化;也有人設成很舊的日期,用不到新特性。正確做法:新專案用 C3 自動填好的近期日期即可;之後保持穩定,只在明確需要某個新 runtime 功能時才手動往前推,並在推之前查官方的 compatibility dates 對照表確認影響。切記不能設成未來日期(會被拒絕)。

坑二:binding 名稱與程式碼對不上,env.XXX 是 undefined。

設定寫 "binding": "CACHE",程式卻用 env.KV 或 env.cache 存取,拿到 undefined。正確做法:謹記「設定檔的 binding 值 = env 上的屬性名」,逐字核對大小寫與拼字完全一致;改動 binding 後執行 wrangler types 重新生成型別,IDE 才會正確提示。

坑三:把 JSONC 當成純 JSON,或忘了它能寫註解。

有人以為 wrangler.jsonc 是嚴格 JSON,不敢寫註解、或不小心用了純 JSON 工具去驗證而報錯。正確做法:JSONC = JSON + 註解,你可以也應該用 // 為複雜綁定加註解,提升可讀性;但也別忘了它終究是 JSON——逗號規則要遵守(物件/陣列最後一個元素後不要多加逗號,某些工具對尾隨逗號較嚴格),字串一律用雙引號。搭配頂端的 $schema 欄位,VS Code 會即時幫你抓出語法與欄位錯誤。

坑四:把敏感值塞進 vars。

vars 是明文存在設定檔並會 commit 進版控的,把 API Key、資料庫密碼放進去等於公開。正確做法:敏感值一律用 Secrets(wrangler secret put)或本地的 .dev.vars,vars 只放非敏感的設定值(環境名稱、log 等級、公開的 API base URL 等)。這正是下一篇要深入的主題。

坑五:想停用 Cron 卻直接刪掉 triggers。

刪掉 triggers 欄位並不會清除已部署的 Cron,舊排程仍在跑。正確做法:要停用所有 Cron,明確把 "crons": [] 設成空陣列再部署。

最佳實踐小結: 記五條——compatibility_date 設定後保持穩定、需要新功能才有意識更新;binding 名稱與 env.XXX 逐字對齊、改完跑 wrangler types;善用 JSONC 註解 + $schema 取得 IDE 驗證;敏感值進 Secrets、vars 只放非敏感值;停用 Cron 用空陣列。守住這五條,你的設定檔就穩了。

小結

上一篇《Wrangler 入門》,我們認識了 Cloudflare 官方 CLI,走過安裝、登入、建專案、dev 到 deploy 的完整流程。這一篇,我們把幕後那份指揮全局的設定檔——wrangler.jsonc——徹底拆開:

• 四大核心欄位——name(Worker 名稱)、main(入口檔)、compatibility_date(凍結 runtime 行為的日期錨點)、compatibility_flags(如 nodejs_compat 的細粒度開關)。
• 各種 binding 宣告——KV、R2、D1、Durable Objects、Queues、AI、vars,核心心智模型是「設定檔的 binding 值 = env 上的屬性名」。
• 路由、觸發與觀測——routes vs workers_dev 決定對外網址、triggers 設 Cron、assets 服務靜態資源、observability 開儀表板、limits 設資源上限。
• 格式選擇——JSONC(JSON with Comments)已取代舊版 TOML 成為推薦格式,搭配 $schema 可獲得 IDE 自動完成與即時驗證;停用 Cron 要用空陣列而非刪欄位。

你可能已經注意到一個伏筆:我們反覆強調「敏感值不要放 vars,要用 Secrets」,還在完整範例裡用 env 區分了 staging 與 production 的概念。這兩件事——多環境管理與 Secrets——正是把 Worker 從「玩具專案」推向「正式生產」的關鍵一步。下一篇《環境管理與 Secrets》,我們就要把 env 多環境設定與 wrangler secret 的安全實踐一次講透,讓你的 staging 與 production 各行其道、敏感資訊滴水不漏。

想先查閱官方對每個設定欄位的完整說明,可以隨時參考 Cloudflare 官方 Wrangler 設定文件。設定檔這一課已就緒,我們下一篇《環境管理與 Secrets》見。