Wrangler Flagship 怎麼用？用 CLI 建立與驗證 Cloudflare feature flag

先確認 Wrangler 版本與登入方式#

官方文件指出，wrangler flagship 需要 Wrangler v4.107.0 以上。先確認你實際執行的 CLI，而不是只看 repository 裡的 lockfile：

1
pnpm wrangler --version

可以使用互動式登入：

1
pnpm wrangler login

在 CI 則使用 CLOUDFLARE_API_TOKEN。權限至少拆成兩層：

官方提醒，多數寫入操作在修改前還會讀取目前旗標定義，因此實際執行寫入的 token 通常需要同時有 read 和 write。只做預覽或驗證的 CI 可以先使用 read-only token，避免把 flagship:write 放進每個 Pull Request。

建立 app 和第一個 boolean flag#

Flagship 指令會把 app ID 放在 flags 子指令的第一個位置。第一次建立 app：

1
pnpm wrangler flagship apps create checkout-service \
2
  --binding FLAGS \
3
  --update-config

--binding FLAGS 會把新建立的資源綁到 Worker 設定檔；如果你只想先在控制面建立 app，也可以不帶 binding。建立後列出 app，取得後續指令要使用的 ID：

1
pnpm wrangler flagship apps list --json

接著建立一個預設關閉的 boolean flag：

1
pnpm wrangler flagship flags create <APP_ID> new-checkout --json

官方文件說明，沒有另外提供 variations 時，Wrangler 會建立 on=true、off=false，並預設服務 off。這個預設值適合先把程式碼路徑部署上去，再分開決定何時開放流量。

Targeting 規則要先用 evaluate 驗證#

建立旗標時可以加入 compact rule：

1
pnpm wrangler flagship flags create <APP_ID> premium-banner \
2
  -V on=true \
3
  -V off=false \
4
  --default off \
5
  --rule 'serve=on; when=plan equals enterprise AND country in [US,CA]; rollout=25%@user_id' \
6
  --json

規則語法有幾個容易漏掉的細節：AND、OR 要在未被引號包住時使用大寫；值裡有保留字或分隔符號時要加引號；深層條件可以改用 --rule-json。Wrangler 會驗證 compact rule 和 JSON rule 的格式，但語法通過不代表你的產品條件正確。

先用明確 context 做評估：

1
pnpm wrangler flagship flags evaluate <APP_ID> premium-banner \
2
  --context plan=enterprise \
3
  --context country=US \
4
  --targeting-key user-42 \
5
  --json

至少要測一個符合條件和一個不符合條件的 context，再確認 percentage rollout 使用的 targeting key 在同一位使用者身上保持穩定。這裡的 evaluate 是控制面驗證，不等於已經有真實流量通過 Worker；runtime 端仍要用自己的測試請求確認 binding 和應用程式路徑。

Rollout、split 和 disable 要分開審核#

當 flag 和 targeting 都驗證完，才進入流量操作。官方的 rollout 形式是：

1
pnpm wrangler flagship flags rollout <APP_ID> premium-banner \
2
  --to on \
3
  --percentage 10 \
4
  --by user_id \
5
  --json

rollout 可能會取代既有 targeting rules；如果現有規則含條件，Wrangler 可能要求確認或 --force。--force 不應該只是為了讓 CI 不停下來就加上，先在 Pull Request 或變更紀錄中保留目前規則與目標流量。

需要立即關閉時，使用 disable：

1
pnpm wrangler flagship flags disable <APP_ID> premium-banner --json

這個指令適合當 kill switch，但它不會代替事故處理。仍要記下誰執行、哪個 app／key、原本 variation 和後續恢復條件。若要查看旗標變更紀錄：

1
pnpm wrangler flagship flags changelog <APP_ID> premium-banner --json

CI 寫入流程要保留 dry-run 思維#

Flagship CLI 文件提供 --json 輸出，適合讓 CI 或其他腳本解析結果。可以把流程拆成三個權限階段：

1. PR 檢查只做 apps list、flags get、flags evaluate，使用 read-only token。
2. 合併後的變更工作流產生預計 rollout 參數，讓人審核 app ID、key、variation 和百分比。
3. 正式寫入工作流才使用 write token，執行後立即讀回 flag 和 changelog。

如果 repository 需要管理多個 Cloudflare 帳號，也要把 token／profile 和工作目錄的對應寫清楚，可參考 Wrangler auth profiles 避免部署錯環境。Flagship 的 app ID 和 Worker 的 account scope 不能只靠命令列當下的預設登入狀態推測。

常見失敗不是 flag 語法，而是邊界錯了#

先把控制面操作和 Worker runtime 請求分開，排錯會比把所有問題都叫成「feature flag 沒生效」更快。

結論：先讀取和評估，再把寫入權限放進流程#

wrangler flagship 適合把 feature flag 操作帶進 CLI 和 CI，但可審核的重點不在指令數量，而在權限與順序：read-only 盤點、evaluate 驗證、審核 rollout、最後才保留 write token 執行。需要緊急處理時可以 disable，但仍要保留 changelog 和恢復條件。

常見問題#