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 以测量启动时间并检测超出启动时间限制的脚本。
使用环境进行 staging/production：在配置中定义 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

可观测性

尾部日志

# 流式传输实时日志
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 分离 staging/production。
设置 compatibility_date：每季度更新以获取新的运行时功能。
使用 .dev.vars 存储本地密钥：切勿将密钥提交到配置中。
先在本地测试：部署前使用本地绑定运行 wrangler dev。
在重大部署前使用 --dry-run：验证更改而不实际部署。
切勿在命令中嵌入密钥：使用交互式提示（wrangler secret put）、基于文件的输入（wrangler secret bulk）或安全的 CI 环境变量。切勿通过 echo、日志或 CLI 参数传递密钥值。

你可能还喜欢

runtime

37Kdevops-cloud

@copilotkit/runtime — mount a fetch-native CopilotRuntime on any JS server, wire middleware, pick an AgentRunner, instantiate BuiltInAgent (Factory Mode with TanStack AI is the preferred default) or plug in any of 12 external agent frameworks (Mastra, LangGraph, CrewAI Crews/Flows, PydanticAI, ADK, LlamaIndex, Agno, AWS Strands, MS Agent Framework, AG2, A2A), enable Intelligence mode for durable threads + websocket, register server-side tools via defineTool, and wire voice transcription. Uses the fetch-based createCopilotRuntimeHandler primitive — the Express/Hono adapters are discouraged. Load the reference under references/ that matches your task.

copilotkit

获取

cloud-design-patterns

37Kdevops-cloud

分布式系统架构的云设计模式，涵盖可靠性、性能、消息传递、安全性和部署等 5 大类共 42 种行业标准设计模式。适用于设计、评审或实现分布式系统架构等场景。

github

获取

claude-automation-recommender

33Kdevops-cloud

分析代码库并推荐适合的 Claude Code 自动化方案（包含 Hooks、Subagents、Skills、Plugins 以及 MCP 服务端）。当用户询问自动化推荐、希望优化其 Claude Code 配置、提及改进 Claude Code 工作流、询问如何为新项目首次配置 Claude Code，或想了解应该使用哪些 Claude Code 功能时使用。

anthropics

获取

继续探索

浏览 devops-cloud 热门 Skills 最近更新

wrangler

相关 Skills

Wrangler CLI

检索来源

第一步：检查 Wrangler 是否已安装，若未安装则进行安装

关键指南

快速开始：新建 Worker

快速参考：核心命令

配置 (wrangler.jsonc)

最小配置

完整配置（含绑定）

从配置生成类型

本地开发

启动开发服务器

本地开发的远程绑定

本地密钥

部署

部署 Worker

管理密钥

版本和回滚

KV（键值存储）

管理命名空间

管理键

配置绑定

R2（对象存储）

管理存储桶

管理对象

配置绑定

D1（SQL 数据库）

管理数据库

执行 SQL

迁移

导出/备份

配置绑定

Vectorize（向量数据库）

管理索引

管理向量

配置绑定

Hyperdrive（数据库加速器）

管理配置

配置绑定

Workers AI

列出模型

配置绑定

Queues

管理队列

配置绑定

Containers

构建和推送镜像

管理容器

管理镜像

管理外部注册表

Workflows

管理工作流

管理工作流实例

配置绑定

Pipelines

管理管道

配置绑定

Secrets Store

管理存储

管理存储中的密钥

配置绑定

Pages（前端部署）

可观测性

尾部日志

配置日志记录

测试

使用 Vitest 进行本地测试

测试定时事件

故障排除

常见问题

调试命令

最佳实践

你可能还喜欢

runtime

cloud-design-patterns

claude-automation-recommender

继续探索