wrangler

Name: wrangler
Author: cloudflare

Wrangler CLI

你對 Wrangler CLI 旗標、設定欄位與子指令的知識可能已過時。對於任何 Wrangler 任務，請優先檢索而非依賴預先訓練的知識。

檢索來源

在撰寫或審查 Wrangler 指令與設定之前，請先取得最新資訊。不要依賴內建知識來處理 CLI 旗標、設定欄位或繫結形狀。

來源	如何檢索	用途
Wrangler 文件	`https://developers.cloudflare.com/workers/wrangler/`	CLI 指令、旗標、設定參考
Wrangler 設定結構描述	`node_modules/wrangler/config-schema.json`	設定欄位、繫結形狀、允許值
Cloudflare 文件	搜尋工具或 `https://developers.cloudflare.com/workers/`	API 參考、相容性日期/旗標

第一步：檢查 Wrangler 是否已安裝，若未安裝則進行安裝

執行以下指令檢查 Wrangler 是否已安裝：

wrangler --version  # 需要 v4.x 以上版本

如果 Wrangler 未安裝，你應該執行以下指令進行安裝：

npm install -D wrangler@latest

在可能的情況下，你應該使用 Wrangler 而非手動建構 API 請求。

主要指南

使用 wrangler.jsonc：偏好 JSON 設定而非 TOML。較新的功能僅支援 JSON。
設定 compatibility_date：使用近期日期（30 天內）。請查閱 https://developers.cloudflare.com/workers/configuration/compatibility-dates/
設定變更後產生型別：執行 wrangler types 以更新 TypeScript 繫結。
本機開發預設使用本機儲存：除非設定 remote: true，否則繫結使用本機模擬。
分析 Worker 啟動時間：執行 wrangler check startup 以測量啟動時間並偵測超過啟動時間限制的腳本。
為測試/正式環境使用環境設定：在設定中定義 env.staging 和 env.production。

快速開始：新增 Worker

# 初始化新專案
npx wrangler init my-worker

# 或使用框架
npx create-cloudflare@latest my-app

快速參考：核心指令

任務	指令
啟動本機開發伺服器	`wrangler dev`
部署至 Cloudflare	`wrangler deploy`
部署預演	`wrangler deploy --dry-run`
產生 TypeScript 型別	`wrangler types`
分析 Worker 啟動時間	`wrangler check startup`
檢視即時日誌	`wrangler tail`
刪除 Worker	`wrangler delete`
驗證狀態	`wrangler whoami`

設定 (wrangler.jsonc)

最小設定

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "name": "my-worker",
  "main": "src/index.ts",
  "compatibility_date": "2026-01-01"
}

完整設定（含繫結）

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "name": "my-worker",
  "main": "src/index.ts",
  "compatibility_date": "2026-01-01",
  "compatibility_flags": ["nodejs_compat"],

  // 環境變數
  "vars": {
    "ENVIRONMENT": "production"
  },

  // KV 命名空間
  "kv_namespaces": [
    { "binding": "KV", "id": "<KV_NAMESPACE_ID>" }
  ],

  // R2 儲存桶
  "r2_buckets": [
    { "binding": "BUCKET", "bucket_name": "my-bucket" }
  ],

  // D1 資料庫
  "d1_databases": [
    { "binding": "DB", "database_name": "my-db", "database_id": "<DB_ID>" }
  ],

  // Workers AI（一律遠端）
  "ai": { "binding": "AI" },

  // Vectorize
  "vectorize": [
    { "binding": "VECTOR_INDEX", "index_name": "my-index" }
  ],

  // Hyperdrive
  "hyperdrive": [
    { "binding": "HYPERDRIVE", "id": "<HYPERDRIVE_ID>" }
  ],

  // Durable Objects
  "durable_objects": {
    "bindings": [
      { "name": "COUNTER", "class_name": "Counter" }
    ]
  },

  // Cron 觸發器
  "triggers": {
    "crons": ["0 * * * *"]
  },

  // 環境
  "env": {
    "staging": {
      "name": "my-worker-staging",
      "vars": { "ENVIRONMENT": "staging" }
    }
  }
}

從設定產生型別

# 產生 worker-configuration.d.ts
wrangler types

# 自訂輸出路徑
wrangler types ./src/env.d.ts

# 檢查型別是否為最新（CI）
wrangler types --check

本機開發

啟動開發伺服器

# 本機模式（預設）- 使用本機儲存模擬
wrangler dev

# 指定環境
wrangler dev --env staging

# 強制僅本機（停用遠端繫結）
wrangler dev --local

# 遠端模式 - 在 Cloudflare 邊緣執行（舊版）
wrangler dev --remote

# 自訂連接埠
wrangler dev --port 8787

# HTML 變更時即時重新載入
wrangler dev --live-reload

# 測試排程/cron 處理器
wrangler dev --test-scheduled
# 然後造訪：http://localhost:8787/__scheduled

本機開發的遠端繫結

在繫結設定中使用 remote: true 以在本機執行時連線至實際資源：

{
  "r2_buckets": [
    { "binding": "BUCKET", "bucket_name": "my-bucket", "remote": true }
  ],
  "ai": { "binding": "AI", "remote": true },
  "vectorize": [
    { "binding": "INDEX", "index_name": "my-index", "remote": true }
  ]
}

建議的遠端繫結：AI（必要）、Vectorize、Browser Rendering、mTLS、Images。

本機機密

建立 .dev.vars 以存放本機開發機密：

API_KEY=local-dev-key
DATABASE_URL=postgres://localhost:5432/dev

部署

部署 Worker

# 部署至正式環境
wrangler deploy

# 部署特定環境
wrangler deploy --env staging

# 預演（驗證但不部署）
wrangler deploy --dry-run

# 保留儀表板設定的變數
wrangler deploy --keep-vars

# 壓縮程式碼
wrangler deploy --minify

管理機密

安全性：切勿將機密值作為指令引數傳遞或透過 echo 管道傳送。
使用互動式提示（建議）、從檔案管道傳送，或使用 secret bulk。
切勿在指令中輸出、記錄或硬編碼機密值。

# 設定機密 — 互動式提示（建議，wrangler 會安全地要求輸入值）
wrangler secret put API_KEY

# 從檔案設定機密（適用於 PEM 金鑰、CI 環境）
wrangler secret put PRIVATE_KEY < path/to/private-key.pem

# 列出機密
wrangler secret list

# 刪除機密
wrangler secret delete API_KEY

# 從 JSON 檔案大量設定機密（請勿將此檔案提交至版本控制）
wrangler secret bulk secrets.json

版本與回退

# 列出近期版本
wrangler versions list

# 檢視特定版本
wrangler versions view <VERSION_ID>

# 回退至上一版本
wrangler rollback

# 回退至特定版本
wrangler rollback <VERSION_ID>

KV（鍵值儲存）

管理命名空間

# 建立命名空間
wrangler kv namespace create MY_KV

# 列出命名空間
wrangler kv namespace list

# 刪除命名空間
wrangler kv namespace delete --namespace-id <ID>

管理鍵

# 寫入值
wrangler kv key put --namespace-id <ID> "key" "value"

# 寫入並設定到期時間（秒）
wrangler kv key put --namespace-id <ID> "key" "value" --expiration-ttl 3600

# 取得值
wrangler kv key get --namespace-id <ID> "key"

# 列出鍵
wrangler kv key list --namespace-id <ID>

# 刪除鍵
wrangler kv key delete --namespace-id <ID> "key"

# 從 JSON 大量寫入
wrangler kv bulk put --namespace-id <ID> data.json

設定繫結

{
  "kv_namespaces": [
    { "binding": "CACHE", "id": "<NAMESPACE_ID>" }
  ]
}

R2（物件儲存）

管理儲存桶

# 建立儲存桶
wrangler r2 bucket create my-bucket

# 建立並指定位置提示
wrangler r2 bucket create my-bucket --location wnam

# 列出儲存桶
wrangler r2 bucket list

# 取得儲存桶資訊
wrangler r2 bucket info my-bucket

# 刪除儲存桶
wrangler r2 bucket delete my-bucket

管理物件

# 上傳物件
wrangler r2 object put my-bucket/path/file.txt --file ./local-file.txt

# 下載物件
wrangler r2 object get my-bucket/path/file.txt

# 刪除物件
wrangler r2 object delete my-bucket/path/file.txt

設定繫結

{
  "r2_buckets": [
    { "binding": "ASSETS", "bucket_name": "my-bucket" }
  ]
}

D1（SQL 資料庫）

管理資料庫

# 建立資料庫
wrangler d1 create my-database

# 建立並指定位置
wrangler d1 create my-database --location wnam

# 列出資料庫
wrangler d1 list

# 取得資料庫資訊
wrangler d1 info my-database

# 刪除資料庫
wrangler d1 delete my-database

執行 SQL

# 執行 SQL 指令（遠端）
wrangler d1 execute my-database --remote --command "SELECT * FROM users"

# 執行 SQL 檔案（遠端）
wrangler d1 execute my-database --remote --file ./schema.sql

# 在本機執行
wrangler d1 execute my-database --local --command "SELECT * FROM users"

遷移

# 建立遷移
wrangler d1 migrations create my-database create_users_table

# 列出待處理遷移
wrangler d1 migrations list my-database --local

# 在本機套用遷移
wrangler d1 migrations apply my-database --local

# 在遠端套用遷移
wrangler d1 migrations apply my-database --remote

匯出/備份

# 匯出結構與資料
wrangler d1 export my-database --remote --output backup.sql

# 僅匯出結構
wrangler d1 export my-database --remote --output schema.sql --no-data

設定繫結

{
  "d1_databases": [
    {
      "binding": "DB",
      "database_name": "my-database",
      "database_id": "<DATABASE_ID>",
      "migrations_dir": "./migrations"
    }
  ]
}

Vectorize（向量資料庫）

管理索引

# 建立索引並指定維度
wrangler vectorize create my-index --dimensions 768 --metric cosine

# 使用預設設定建立（自動設定維度/度量）
wrangler vectorize create my-index --preset @cf/baai/bge-base-en-v1.5

# 列出索引
wrangler vectorize list

# 取得索引資訊
wrangler vectorize get my-index

# 刪除索引
wrangler vectorize delete my-index

管理向量

# 從 NDJSON 檔案插入向量
wrangler vectorize insert my-index --file vectors.ndjson

# 查詢向量
wrangler vectorize query my-index --vector "[0.1, 0.2, ...]" --top-k 10

設定繫結

{
  "vectorize": [
    { "binding": "SEARCH_INDEX", "index_name": "my-index" }
  ]
}

Hyperdrive（資料庫加速器）

管理設定

# 建立設定
wrangler hyperdrive create my-hyperdrive \
  --origin-host db.example.com \
  --origin-port 5432 \
  --database my-database \
  --origin-user db-user \
  --origin-password "$DB_PASSWORD"

# 或使用環境變數中的連線字串
wrangler hyperdrive create my-hyperdrive \
  --connection-string "$HYPERDRIVE_CONNECTION_STRING"

# 列出設定
wrangler hyperdrive list

# 取得設定詳細資訊
wrangler hyperdrive get <HYPERDRIVE_ID>

# 更新設定
wrangler hyperdrive update <HYPERDRIVE_ID> \
  --origin-password "$DB_PASSWORD"

# 刪除設定
wrangler hyperdrive delete <HYPERDRIVE_ID>

設定繫結

{
  "compatibility_flags": ["nodejs_compat"],
  "hyperdrive": [
    { "binding": "HYPERDRIVE", "id": "<HYPERDRIVE_ID>" }
  ]
}

Workers AI

列出模型

# 列出可用模型
wrangler ai models

# 列出微調模型
wrangler ai finetune list

設定繫結

{
  "ai": { "binding": "AI" }
}

注意：Workers AI 一律在遠端執行，即使在本機開發中也會產生使用費用。

Queues

管理佇列

# 建立佇列
wrangler queues create my-queue

# 列出佇列
wrangler queues list

# 刪除佇列
wrangler queues delete my-queue

# 新增消費者至佇列
wrangler queues consumer add my-queue my-worker

# 移除消費者
wrangler queues consumer remove my-queue my-worker

設定繫結

{
  "queues": {
    "producers": [
      { "binding": "MY_QUEUE", "queue": "my-queue" }
    ],
    "consumers": [
      {
        "queue": "my-queue",
        "max_batch_size": 10,
        "max_batch_timeout": 30
      }
    ]
  }
}

Containers

建置與推送映像檔

# 建置容器映像檔
wrangler containers build -t my-app:latest .

# 建置並推送（單一指令）
wrangler containers build -t my-app:latest . --push

# 將現有映像檔推送至 Cloudflare 登錄
wrangler containers push my-app:latest

管理容器

# 列出容器
wrangler containers list

# 取得容器資訊
wrangler containers info <CONTAINER_ID>

# 刪除容器
wrangler containers delete <CONTAINER_ID>

管理映像檔

# 列出登錄中的映像檔
wrangler containers images list

# 刪除映像檔
wrangler containers images delete my-app:latest

管理外部登錄

安全性：切勿在指令中硬編碼登錄憑證。請使用環境變數。

# 列出已設定的登錄
wrangler containers registries list

# 設定外部登錄（例如 ECR）
wrangler containers registries configure <DOMAIN> \
  --aws-access-key-id "$AWS_ACCESS_KEY_ID"

# 設定 DockerHub
wrangler containers registries configure <DOMAIN> \
  --dockerhub-username "$DOCKERHUB_USERNAME"

# 刪除登錄設定
wrangler containers registries delete <DOMAIN>

Workflows

管理工作流程

# 列出工作流程
wrangler workflows list

# 描述工作流程
wrangler workflows describe my-workflow

# 觸發工作流程實例
wrangler workflows trigger my-workflow

# 觸發並帶參數
wrangler workflows trigger my-workflow --params '{"key": "value"}'

# 刪除工作流程
wrangler workflows delete my-workflow

管理工作流程實例

# 列出實例
wrangler workflows instances list my-workflow

# 描述實例
wrangler workflows instances describe my-workflow <INSTANCE_ID>

# 終止實例
wrangler workflows instances terminate my-workflow <INSTANCE_ID>

設定繫結

{
  "workflows": [
    {
      "binding": "MY_WORKFLOW",
      "name": "my-workflow",
      "class_name": "MyWorkflow"
    }
  ]
}

Pipelines

管理管線

# 建立管線
wrangler pipelines create my-pipeline --r2 my-bucket

# 列出管線
wrangler pipelines list

# 顯示管線詳細資訊
wrangler pipelines show my-pipeline

# 更新管線
wrangler pipelines update my-pipeline --batch-max-mb 100

# 刪除管線
wrangler pipelines delete my-pipeline

設定繫結

{
  "pipelines": [
    { "binding": "MY_PIPELINE", "pipeline": "my-pipeline" }
  ]
}

Secrets Store

管理存放庫

# 建立存放庫
wrangler secrets-store store create my-store

# 列出存放庫
wrangler secrets-store store list

# 刪除存放庫
wrangler secrets-store store delete <STORE_ID>

管理存放庫中的機密

# 新增機密至存放庫
wrangler secrets-store secret put <STORE_ID> my-secret

# 列出存放庫中的機密
wrangler secrets-store secret list <STORE_ID>

# 取得機密
wrangler secrets-store secret get <STORE_ID> my-secret

# 從存放庫刪除機密
wrangler secrets-store secret delete <STORE_ID> my-secret

設定繫結

{
  "secrets_store_secrets": [
    {
      "binding": "MY_SECRET",
      "store_id": "<STORE_ID>",
      "secret_name": "my-secret"
    }
  ]
}

Pages（前端部署）

# 建立 Pages 專案
wrangler pages project create my-site

# 將目錄部署至 Pages
wrangler pages deploy ./dist

# 部署至特定分支
wrangler pages deploy ./dist --branch main

# 列出部署
wrangler pages deployment list --project-name my-site

可觀測性

Tail 日誌

# 串流即時日誌
wrangler tail

# 追蹤特定 Worker
wrangler tail my-worker

# 依狀態篩選
wrangler tail --status error

# 依搜尋詞篩選
wrangler tail --search "error"

# JSON 輸出
wrangler tail --format json

設定記錄

{
  "observability": {
    "enabled": true,
    "head_sampling_rate": 1
  }
}

測試

使用 Vitest 進行本機測試

npm install -D @cloudflare/vitest-pool-workers vitest

vitest.config.ts：

import { defineWorkersConfig } from "@cloudflare/vitest-pool-workers/config";

export default defineWorkersConfig({
  test: {
    poolOptions: {
      workers: {
        wrangler: { configPath: "./wrangler.jsonc" },
      },
    },
  },
});

測試排程事件

# 在開發模式中啟用
wrangler dev --test-scheduled

# 透過 HTTP 觸發
curl http://localhost:8787/__scheduled

疑難排解

常見問題

問題	解決方案
`command not found: wrangler`	安裝：`npm install -D wrangler`
驗證錯誤	執行 `wrangler login`
超過啟動時間限制	執行 `wrangler check startup` 以分析啟動時間並產生 CPU 分析資料
設定變更後出現型別錯誤	執行 `wrangler types`
本機儲存未持久化	檢查 `.wrangler/state` 目錄
Worker 中繫結未定義	確認繫結名稱與設定完全相符

除錯指令

# 檢查驗證狀態
wrangler whoami

# 分析 Worker 啟動時間
wrangler check startup

# 檢視設定結構描述
wrangler docs configuration

最佳實務

將 wrangler.jsonc 納入版本控制：視為 Worker 設定的唯一真相來源。
使用自動佈建：省略資源 ID 以在部署時自動建立。
在 CI 中執行 wrangler types：加入建置步驟以捕捉繫結不符。
使用環境設定：透過 env.staging、env.production 區分測試與正式環境。
設定 compatibility_date：每季更新以取得新的執行時期功能。
使用 .dev.vars 存放本機機密：切勿將機密提交至設定檔。
先在本機測試：部署前使用 wrangler dev 搭配本機繫結。
重大部署前使用 --dry-run：在不實際部署的情況下驗證變更。
切勿在指令中嵌入機密：使用互動式提示（wrangler secret put）、檔案輸入（wrangler secret bulk）或安全的 CI 環境變數。切勿透過 echo、記錄或將機密值作為 CLI 引數傳遞。

您可能也喜歡

import-infrastructure-as-code

37Kdevops-cloud

Import existing Azure resources into Terraform using Azure CLI discovery and Azure Verified Modules (AVM). Use when asked to reverse-engineer live Azure infrastructure, generate Infrastructure as Code from existing subscriptions/resource groups/resource IDs, map dependencies, derive exact import addresses from downloaded module source, prevent configuration drift, and produce AVM-based Terraform files ready for validation and planning across any Azure resource type.

github

獲取

mcp-builder

10Kdevops-cloud

**所有 MCP 伺服器工作的必讀指南** - mcp-use 框架的最佳實務與模式。 **在進行任何 MCP 伺服器工作前，請先閱讀本文件**，包括： - 建立新的 MCP 伺服器 - 修改現有 MCP 伺服器（新增/更新工具、資源、提示、小工具） - 除錯 MCP 伺服器問題或錯誤 - 審查 MCP 伺服器程式碼的品質、安全性或效能 - 回答關於 MCP 開發或 mcp-use 模式的問題 - 對 server.tool()、server.resource()、server.prompt() 或小工具進行任何變更本技能包含重要的架構決策、安全模式與常見陷阱。在實作 MCP 功能前，務必查閱相關的參考檔案。

mcp-use

獲取

nuxt

5.4Kdevops-cloud

Nuxt 全端 Vue 框架，支援 SSR、自動匯入與基於檔案的路由。適用於開發 Nuxt 應用程式、伺服器路由、useFetch、中介軟體或混合渲染。

antfu

獲取

繼續探索

瀏覽 devops-cloud 熱門 Skills 最近更新