跳轉至

建立 2026-11-22 更新 2026-11-22

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
API_KEY=local-test-key

不要提交機密檔

把 .dev.vars 與 .env 加進 .gitignore。正式環境的機密一律用 wrangler secret put 設定。

相關資料