---
title: "Wrangler 命令速查：部署一个 Worker 真正用到的 8 条"
date: 2026-11-10
slug: wrangler-commands-cheatsheet
canonical: https://kernelranch.com/blog/2026/11/wrangler-commands-cheatsheet
markdown_url: https://kernelranch.com/blog/2026/11/wrangler-commands-cheatsheet.md
tags: ["cloudflare", "workers", "wrangler", "cli", "cheatsheet"]
---Wrangler 有几十条子命令，日常真正敲的就这 8 条。版本以本机 4.146.0 为准。

## 1. 八条命令

```bash
wrangler whoami                 # 看登录态、账号 ID、token 权限范围
wrangler deploy                 # 部署（读 wrangler.toml）
wrangler dev                    # 本地跑，默认 127.0.0.1:8787
wrangler tail <name>            # 线上实时日志
wrangler delete <name>          # 删除 Worker
wrangler deployments list --name <name>   # 看部署记录
wrangler kv namespace create <名称>        # 建 KV 命名空间
wrangler secret put <KEY>       # 写加密变量
```

`whoami` 值得第一个跑：它会把 token 的权限范围列出来。只有 `workers` 与 `workers_kv` 写权限时，DNS、Pages、R2 相关命令都会失败，提前知道能省掉很多试错。

## 2. 部署输出怎么读

```
Total Upload: 1.37 KiB / gzip: 0.80 KiB
Worker Startup Time: 2 ms
Uploaded cf53-demo (3.13 sec)
Deployed cf53-demo triggers (1.60 sec)
  https://cf53-demo.<你的账号>.workers.dev
Current Version ID: adefe73b-...
```

四行各有用处：

| 字段 | 含义 | 异常信号 |
|---|---|---|
| Total Upload | 打包后体积（含 gzip） | 超过几 MB 通常意味着误打包了 node_modules |
| Worker Startup Time | 冷启动耗时 | 超过 50ms 要检查顶层代码有没有做重活 |
| Uploaded | 上传耗时 | 与包体积成正比，可用来判断网络 |
| Deployed triggers | 路由/域名生效耗时 | 卡住通常是域名状态不是 Active |

`Version ID` 记下来，回滚和排查时用得上。

## 3. 五个坑

自定义域会关掉 workers.dev。配置 `custom_domain = true` 后部署，wrangler 会警告 workers.dev 路由被禁用，此时原来的 `xxx.workers.dev` 地址直接 404。想要两个都能用，就别用 custom_domain，改成 route。

`deployments list` 对不存在的 Worker 报 10007。返回的是 `This Worker does not exist on your account. [code: 10007]`，这正好可以用来确认删除是否成功。

`kv key list` 默认只查本地模拟。要查线上得加 `--remote`，否则你会以为数据丢了。

`--dry-run` 只打包不上传。改配置后先用它验证构建，比直接 deploy 快，也不会产生新版本。

`-c` 可以指定另一份配置。同一份代码要部署到不同环境时，比改 `wrangler.toml` 安全。

## 4. 一条最小工作流

```bash
wrangler whoami
wrangler deploy --dry-run
wrangler deploy
curl -s -o /dev/null -w "%{http_code}\n" https://<你的地址>/
wrangler tail <name>
wrangler delete <name>
```

先 dry-run 看打包结果，再 deploy，然后 curl 确认状态码，需要排错时再开 tail。这个顺序能避免"部署成功但访问 404"这种低级困惑。

## 小结

Wrangler 的复杂度不在命令数量，在于权限与环境：token 能做什么、域名是不是 Active、workers.dev 有没有被关掉，这三件事决定了部署能不能落地。

记住两个习惯：动手前 `whoami`，改完先 `--dry-run`。它们能把大部分失败挡在产生副作用之前。

## 数据来源与检索时间

检索时间 2026-11-10。命令行为与输出均来自本机实际执行（wrangler 4.146.0）。

| 来源 | URL | 对应数据 |
|---|---|---|
| Cloudflare Workers 入门指南 | https://developers.cloudflare.com/workers/get-started/guide/ | `wrangler deploy` / `wrangler dev` 的官方流程 |
| Workers 路由文档 | https://developers.cloudflare.com/workers/configuration/routing/routes/ | 自定义域与 workers.dev 的关系 |
| KV 文档 | https://developers.cloudflare.com/kv/ | `kv namespace create`、`kv key list --remote` 的用法 |

## 核验说明

- 第 2 节的部署输出是本机部署 `cf53-demo` 的真实终端输出；第 3 节的 10007 报错、workers.dev 被禁用、`--remote` 默认值都是本机实际遇到并记录的现象。
- 未做：没有测多环境（--env）部署、CI 中的 `wrangler deploy --token` 流程，也没有验证回滚到指定 Version ID 的完整步骤。