Wrangler 使用指引
# Wrangler 使用指引
平台概览与文档入口见 Cloudflare 概览。
Wrangler 是 Cloudflare 的开发与部署 CLI，用来调试、发布 Workers，管理变量、Secret 和资源绑定，也提供 Pages 子命令。本文以直接使用 Wrangler 的 Worker 项目为主，按“本地跑通 → 明确环境 → 发布 → 查看日志”的顺序操作；核对日期：2026-11-05。
| 你要处理的项目 | 使用入口 | 配置重点 |
|---|---|---|
| Worker API、定时任务、边缘逻辑 | wrangler dev、wrangler deploy | main、运行时兼容日期、资源绑定 |
| 已有 Pages 站点或 Pages Functions | wrangler pages … | 构建产物目录、Pages 项目名与分支 |
| 使用 Cloudflare Vite 插件的项目 | 优先使用项目的 npm run dev/build/deploy | 遵循框架配置；环境选择可能使用 CLOUDFLARE_ENV |
Workers 和 Pages 的部署对象不同，不能用 wrangler deploy 代替 wrangler pages deploy。Wrangler 的总入口保留在 官方文档 (opens new window)。
# 1. 进入项目并确认身份
已有项目先看 package.json、锁文件及 wrangler.jsonc / wrangler.toml，沿用项目已有版本和脚本；不要在博客仓库根目录随手安装来操作另一个 Worker。
| 操作 | 命令 | 如何确认 |
|---|---|---|
| 为尚未接入的项目添加 Wrangler | npm install --save-dev wrangler | 安装在目标项目，提交依赖与锁文件 |
| 确认当前实际版本 | npx wrangler --version | 使用项目中的版本，避免全局命令版本不同 |
| 查看当前子命令参数 | npx wrangler deploy --help | 选项以当前安装版本为准 |
| 浏览器 OAuth 登录 | npx wrangler login | 在浏览器确认账号并完成授权 |
| 确认身份和可用账号 | npx wrangler whoami | 核对账号后再操作资源 |
| 退出本机登录 | npx wrangler logout | 不会删除云端 Worker |
Wrangler 应按项目安装，Node.js 使用官方支持的 Current / Active LTS / Maintenance LTS 版本；本机 Node 版本与 Worker 的运行时不是一回事。Worker 运行在 workerd 中。详见 安装与运行要求 (opens new window)。
新项目可以用官方脚手架生成，交互中先选择不部署，完成本地验证再发布：
npm create cloudflare@latest -- demo-api
cd demo-api
2
远程终端中 OAuth 回调不可达时，先查 npx wrangler login --help；支持设备授权的版本可使用 npx wrangler login --device。单独加 --browser=false 只是停止自动打开浏览器，不会消除本机回调要求。参见 登录命令与远程登录 (opens new window)。
# 2. 最小配置与本地调试
新项目优先使用 wrangler.jsonc。以下配置与代码是一组可对照的最小示例；已有项目应修改对应字段，不要覆盖其资源绑定。
wrangler.jsonc：
{
"$schema": "./node_modules/wrangler/config-schema.json",
"name": "demo-api",
"main": "src/index.js",
"compatibility_date": "2026-11-05",
"vars": {
"APP_ENV": "development"
}
}
2
3
4
5
6
7
8
9
src/index.js：
export default {
async fetch(request, env) {
return new Response(`Hello from ${env.APP_ENV}`, {
headers: { "content-type": "text/plain; charset=utf-8" }
});
}
};
2
3
4
5
6
7
| 字段 | 作用 | 容易混淆的地方 |
|---|---|---|
name | Worker 名称 | 决定操作的服务，不是显示备注 |
main | Worker 入口文件 | 路径需与实际代码一致 |
compatibility_date | 选择运行时兼容行为 | 不是发布时间；老项目升级日期前需回归 |
vars | 非敏感运行变量 | 在代码中通过 env.APP_ENV 读取，不放密码 |
| 资源绑定 | 把 KV、D1、R2 等接入 env | 绑定声明不能替代资源创建；各环境需明确配置 |
配置格式与字段依据 Wrangler 配置文档 (opens new window)。JSONC 支持注释；不要同时维护两份意图相同的 JSONC/TOML 配置。
# 在项目目录执行；强制本地模式，禁用远程资源绑定。
npx wrangler dev --local --port 8787
# 另一个终端验证响应。
curl http://localhost:8787/
2
3
4
5
预期响应是 Hello from development。修改代码后观察本地终端中的编译结果和请求日志。按 Ctrl+C 停止服务。
| 场景 | 命令 | 影响范围 |
|---|---|---|
| 本地开发 | npx wrangler dev --local | 本机运行；本地资源数据不等于线上数据 |
| 在 Cloudflare 预览环境执行 | npx wrangler dev --remote | 连接远程资源，写操作可能影响真实数据 |
| 编译检查，不部署 | npx wrangler deploy --dry-run --outdir .wrangler-build | 生成本地产物，不能代替线上请求验证 |
| 明确指定配置文件 | npx wrangler dev --config ./wrangler.jsonc | 适用于多项目、多配置目录 |
| 在指定目录运行 | npx wrangler --cwd ./worker dev --local | 避免从错误目录读取配置 |
dev --remote 不是已经上线服务的日志查看入口；线上请求看 tail。本地运行与远程绑定的边界见 Worker 命令参考 (opens new window)。
# 3. 变量、Secret 与多环境
先分清三种值：
| 类型 | 放在哪里 | 谁读取 |
|---|---|---|
| 非敏感业务变量 | Wrangler 配置的 vars | Worker 的 env |
| 本地调试 Secret | 配置同目录的 .dev.vars，或按规则使用 .env | 本地 Worker 的 env |
| 线上业务 Secret | 通过 Secret 命令或控制台设置 | 对应线上 Worker 的 env |
| Cloudflare 部署凭据 | CI 的 Secret 存储，以环境变量注入 | Wrangler 本身，不是业务 Secret |
本地 .dev.vars 示例只声明名称，实际值在本机填写：
EXTERNAL_API_TOKEN=""
在目标 Worker 项目的 .gitignore 中加入：
.dev.vars*
.env*
.wrangler/
.wrangler-build/
2
3
4
.dev.vars 与 .env 选择一种即可；存在 .dev.vars 时，.env 不再作为本地 Worker 变量来源。选用 .dev.vars.staging 时，该环境文件独立生效，不会再与通用 .dev.vars 合并。文件加载规则见 本地环境变量与 Secret (opens new window)。
多环境不是自动隔离开关。把以下 env 片段合入前面的配置后，每次显式选择目标环境：
{
"env": {
"staging": {
"name": "demo-api-staging",
"vars": { "APP_ENV": "staging" }
},
"production": {
"name": "demo-api-production",
"vars": { "APP_ENV": "production" }
}
}
}
2
3
4
5
6
7
8
9
10
11
12
| 操作 | 命令 |
|---|---|
| 本地以 staging 配置启动 | npx wrangler dev --local --env staging |
| 为 staging 设置 Secret，交互输入值 | npx wrangler secret put EXTERNAL_API_TOKEN --env staging |
| 列出 staging Secret 名称 | npx wrangler secret list --env staging |
| 删除 staging Secret | npx wrangler secret delete EXTERNAL_API_TOKEN --env staging |
vars、资源绑定及 Secret 不会简单从顶层继承到命名环境，需按环境配置。KV/D1/R2 若在两个环境填了同一资源 ID，仍然访问同一份数据。无 --env 时使用顶层配置，不会自动选择 production。参见 环境配置 (opens new window)。
secret list 不返回 Secret 明文；secret put 会立即创建并部署新版本。若需要先生成版本、再单独审批发布，应采用 versions secret put / versions deploy 的版本流程，不能把普通 secret put 当作纯暂存操作。详见 Secret 管理 (opens new window)。
CI 使用 CLOUDFLARE_API_TOKEN，需要时同时提供 CLOUDFLARE_ACCOUNT_ID；按目标账号和资源分配所需权限，通过 CI Secret 注入，不把 Token 写进仓库或命令示例。它们与 Worker 业务代码里的 env.EXTERNAL_API_TOKEN 作用不同。参见 Wrangler 系统环境变量 (opens new window)。
# 4. 部署、查看日志与回退
建议按顺序执行：确认身份 → 核对环境配置 → 本地验证 → dry-run → 部署 → 请求验证与日志观察。
npx wrangler whoami
npx wrangler deploy --dry-run --env staging --outdir .wrangler-build
# 从这里开始修改 Cloudflare 上的服务。
npx wrangler deploy --env staging
npx wrangler tail --env staging --format pretty
2
3
4
5
6
部署完成后使用输出中的 URL 发起请求，再观察对应环境的日志。自定义域名和路由是独立配置项，部署成功不代表任意域名已自动绑定。
| 目的 | 命令 | 说明 |
|---|---|---|
| 发布 staging | npx wrangler deploy --env staging | 上传代码并部署 |
| 发布 production | npx wrangler deploy --env production | 先确认确实要修改正式环境 |
| 查看线上请求日志 | npx wrangler tail --env production | 接入后发起请求，观察日志和异常 |
| 只看失败调用 | npx wrangler tail --env production --status error | 按调用状态过滤 |
| 查看近期代码版本 | npx wrangler versions list --env production | 代码版本不等于已发布记录 |
| 查看近期部署记录 | npx wrangler deployments list --env production | 查看部署状态与记录 |
| 上传版本，暂不发布 | npx wrangler versions upload --env production | 与直接 deploy 区分 |
| 发布已上传版本 | npx wrangler versions deploy --env production | 交互选择版本与流量比例 |
| 回退到明确版本 | npx wrangler rollback VERSION_ID --env production | 用 versions list 中的实际 ID 替换占位符 |
实时 tail 是观察当前请求的入口，不是完整历史日志数据库，高流量下还可能采样；持续审计需另外配置日志留存。版本、部署及命令参数见 Worker 命令参考 (opens new window)。
回退会立即影响线上服务，不会把本地源码、数据库内容或外部资源一起恢复；绑定资源被删除、Durable Object 生命周期变化等情况还会限制回退。不要把代码回退当作数据恢复。参见 回退限制 (opens new window)。
# 5. 已有 Pages 项目怎么操作
以下用于已有 Pages 或明确选用 Direct Upload 的项目，dist 要替换成实际构建输出目录：
| 操作 | 命令 |
|---|---|
| 查看 Pages 项目 | npx wrangler pages project list |
| 构建前端产物 | npm run build |
| 本地预览构建结果及 Functions | npx wrangler pages dev ./dist |
| 上传到指定项目的 main 分支 | npx wrangler pages deploy ./dist --project-name demo-site --branch main |
| 上传 preview 分支 | npx wrangler pages deploy ./dist --project-name demo-site --branch preview |
main 只有被配置为该 Pages 项目的生产分支时才是生产部署，preview 应选不同于生产分支的名称。Wrangler 上传的是已有构建产物，不会替你完成站点构建。参见 Pages Direct Upload (opens new window)。
Pages 配置可通过 pages_build_output_dir 声明构建目录；不要把 Workers 的 env.staging 环境模型直接套到 Pages。已有项目运行 wrangler pages download config 会覆盖本地 Wrangler 配置，应先比较、备份。参见 Pages 配置规则 (opens new window)。
本博客当前仍按仓库自己的 GitHub Pages 流程发布；上面的 Pages 命令是另一个部署方案的操作参考，不表示博客已切换到 Cloudflare，也不要把示例 dist 直接当作本仓库的产物目录。
# 6. 出问题时按这个顺序查
| 现象 | 先检查 | 下一步 |
|---|---|---|
| 命令不存在，或参数与文档不同 | 当前目录、npx wrangler --version | 沿用锁文件版本，查对应子命令 --help |
| OAuth 登录卡住、浏览器回调失败 | 本地/SSH/容器的回调是否可达 | 支持的版本使用 login --device；CI 用 API Token |
| 认证失败、账号不对 | whoami、CI 注入的 Token 与账号 | 检查 Token 权限和账号范围，不反复覆盖项目配置 |
| 本地变量缺失 | 文件是否与配置同目录，是否选择了 --env | 核对 .dev.vars / 环境专属文件及 vars 是否重声明 |
| 本地正常，线上变量或绑定缺失 | 部署环境、Secret 和资源绑定 | 对同一环境检查 Secret 名称及绑定资源 |
| 部署成功却返回 404 | 请求的是哪个 URL、路径和路由 | 先用部署输出 URL 验证，再查自定义域名和应用路由 |
tail 没有输出 | 是否选对 Worker/环境，是否有新请求 | 保持 tail 打开并触发请求，检查过滤与采样 |
| Pages 发布的是旧页面 | 构建目录、项目名、生产分支 | 重新构建并确认上传的目录，不只看 deploy 是否成功 |
需要更细的 CLI 诊断时，可单次执行 WRANGLER_LOG=debug npx wrangler deploy --dry-run --env staging；排障后恢复默认级别，对外分享日志前清理凭据、请求内容和个人路径。Secret 值、账号凭据及真实项目配置不应出现在公开博客示例中。