Cloudflare Wrangler CLI 使用指南

Wrangler 是 Cloudflare Workers 和 CI/CD 流程的官方命令行界面 (CLI) 工具。通过 Wrangler，你可以在本地开发、测试 Cloudflare Workers，并将它们部署到全球的 Cloudflare 网络中。它也支持 Cloudflare Pages 的命令行管理。

Wrangler CLI

1. 环境准备

在使用 Wrangler 之前，请确保你的系统已安装 Node.js 和 npm (或 pnpm/yarn)。

兼容性提示

建议使用最新 LTS 版本的 Node.js 以获得最佳兼容性。

2. 安装 Wrangler

你可以全局安装 Wrangler，也可以作为项目的开发依赖安装。

全局安装 (推荐初学者)

npm install -g wrangler
# 或者使用 yarn
yarn global add wrangler
# 或者使用 pnpm
pnpm add -g wrangler

验证安装：

wrangler --version

项目内安装 (推荐生产环境)

npm install -D wrangler

3. 登录账号 / 授权验证

安装完成后，你需要通过 OAuth 将 Wrangler 连接到你的 Cloudflare 账户。

wrangler login

运行该命令后，浏览器会自动弹出 Cloudflare 的授权页面。点击 "Allow" 即可完成授权。

• 如果是非图形化界面 (如 Linux 服务器)，可以使用 wrangler login --browser=false，然后复制链接在本地浏览器打开。

4. 常用命令详解

初始化项目 (init)

创建一个新的 Workers 项目：

wrangler init my-worker

根据提示回答几个问题（是否使用 TypeScript，是否创建 wrangler.toml 等），Wrangler 会自动为你生成项目模版。

本地开发 (dev)

在本地启动开发服务器，模拟 Cloudflare 边缘环境：

wrangler dev

按 b 可在浏览器打开，按 x 退出。本地开发非常快，支持热更新。

部署上线 (deploy)

将你的代码发布到 Cloudflare 全球网络：

wrangler deploy

• 注意：在旧版本中此命令为 wrangler publish，v3 版本后已变更为 deploy。

5. 管理 Cloudflare Pages

Wrangler 也支持直接管理 Pages 项目（即 Direct Upload 模式）。

部署静态目录

如果你有一个构建好的静态网站目录（例如 dist 或 .vitepress/dist）：

npx wrangler pages deploy dist --project-name=my-awesome-site

实时预览

npx wrangler pages dev dist

常见问题 (FAQ)

Q: wrangler login 无法弹出浏览器？

A: 请检查终端是否有权限调用浏览器，或者尝试使用 wrangler login --browser=false 手动复制鉴权 URL。

Q: 部署后访问报错 1101？

A: 通常是 Worker 代码抛出了异常。建议使用 wrangler tail 命令实时查看线上日志进行调试。

wrangler tail