Wrangler 命令列工具
Wrangler 是 Cloudflare 官方的命令列工具(CLI),用來在本機開發、測試並部署 Workers 與 Pages,也能建立與管理 KV、D1、R2 等資源。大部分在儀表板上點選的操作都能用 Wrangler 完成,方便寫進腳本與 CI 自動化。本頁整理最常用的指令與設定檔寫法。
安裝與登入
建議把 Wrangler 安裝在專案內,讓團隊使用相同版本:
npm install --save-dev wrangler
npx wrangler --version
npx wrangler login # 開啟瀏覽器授權
npx wrangler whoami # 確認目前登入的帳號
在 CI 環境中不能開瀏覽器,改用環境變數 CLOUDFLARE_API_TOKEN 與 CLOUDFLARE_ACCOUNT_ID(建立方式見 直接上傳與 Wrangler)。
常用指令
| 指令 | 用途 |
|---|---|
wrangler dev |
本機啟動 Worker 開發伺服器 |
wrangler deploy |
部署 Worker |
wrangler tail |
即時查看正式環境的 Log(console.log 輸出) |
wrangler secret put API_KEY |
新增加密的 Secret(互動式輸入,不會出現在指令紀錄) |
wrangler versions list |
查看部署版本 |
wrangler rollback |
回復到上一個版本 |
wrangler pages dev <dir> |
本機啟動 Pages 開發伺服器 |
wrangler pages deploy <dir> |
上傳部署 Pages |
wrangler kv namespace create <名稱> |
建立 KV |
wrangler d1 create <名稱> |
建立 D1 資料庫 |
wrangler d1 execute <名稱> --remote --command "SQL" |
對 D1 執行 SQL |
wrangler r2 bucket create <名稱> |
建立 R2 Bucket |
wrangler types |
依設定檔產生 TypeScript 型別(Env) |
以上指令前面都加 npx(例如 npx wrangler dev)。
設定檔:wrangler.jsonc
Wrangler 支援 wrangler.jsonc(建議,可寫註解)與 wrangler.toml 兩種格式。常用欄位:
wrangler.jsonc
{
"$schema": "./node_modules/wrangler/config-schema.json", // 編輯器自動完成
"name": "my-app", // Worker 名稱
"main": "src/index.ts", // 入口檔
"compatibility_date": "2026-11-01", // 執行環境版本
"compatibility_flags": ["nodejs_compat"], // 啟用 Node.js 相容 API
"vars": { "ENVIRONMENT": "production" }, // 一般環境變數(不要放機密)
"assets": { "directory": "./public" }, // 靜態檔案
"observability": { "enabled": true }, // 在儀表板保存 Log
"env": {
"staging": { // npx wrangler deploy --env staging
"name": "my-app-staging",
"vars": { "ENVIRONMENT": "staging" }
}
}
}
本機開發的機密值
本機開發時,Secret 放在專案根目錄的 .dev.vars(格式同 .env):
不要提交機密檔
把 .dev.vars 與 .env 加進 .gitignore。正式環境的機密一律用 wrangler secret put 設定。