【Wrangler（Cloudflare 的官方 CLI）和 npm/npx 的区别一次讲清】

下面这份速读指南，帮你把 Wrangler（Cloudflare 的官方 CLI）和 npm/npx 的区别一次讲清 👇

Wrangler 是什么？

Wrangler 是 Cloudflare Developer Platform 的命令行工具，用来本地开发、配置、部署与运维 Cloudflare Workers 及其配套服务（KV、R2、D1、Queues、Durable Objects、定时任务等）。自 v3 起，Wrangler 支持 wrangler.jsonc/.json 和 wrangler.toml 两种配置格式；Cloudflare 现在更推荐用 JSONC （带注释的 JSON）创建新项目。(Cloudflare Docs)

Wrangler 的本地开发命令 wrangler dev 会在本地模拟 Workers 运行时（底层由 Miniflare/workerd 驱动），因此无需连网就能测试大部分能力。(Cloudflare Docs)

---

Wrangler 能做什么（核心能力一览）

• 本地开发与调试 ：wrangler dev 启动本地服务，热更新、断点/DevTools 调试、更贴近线上环境。(Cloudflare Docs)
• 构建与部署 ：wrangler deploy/wrangler publish 一键发布；也可用 版本化与预览 流程 wrangler versions upload/deploy，适合 CI 分支预览和渐进发布。(Cloudflare Docs)
• KV（键值存储）管理 ：创建命名空间、读写/删除键值：wrangler kv namespace create、wrangler kv:key get/put/delete。(Cloudflare Docs)
• R2（对象存储）管理 ：创建 bucket、做基础对象操作，可用 Wrangler 或仪表盘。(Cloudflare Docs)
• D1（SQLite 数据库） ：wrangler d1 create、迁移、查询等整套命令。(Cloudflare Docs)
• Queues（消息队列） ：创建、列出、订阅/消费者管理等：wrangler queues ...。(Cloudflare Docs)
• Secrets & 环境变量 ：通过 wrangler secret put/delete 管理密钥（密文），配合 .dev.vars 做本地仿真。(Cloudflare Docs, docs.astro.build)
• 日志与可观测性 ：wrangler tail 拉取在线日志，或配置 Tail Worker 做高级处理。(Cloudflare Docs)
• Pages Functions / 多框架集成 ：Wrangler 也用于 Pages Functions 的本地/预览配置。(Cloudflare Docs)

小提示：若你的项目目录里同时 有 wrangler.toml 和 wrangler.json/jsonc，容易"读错配置"。可以用全局参数 --config <path> 明确指定要用哪一个；或者只保留一种配置以避免歧义。(Cloudflare Docs)

---

典型工作流（上手就用）

1. 登录

npx wrangler@latest login

2. 本地开发

npx wrangler@latest dev

（需要特定配置文件时）

npx wrangler@latest dev --config wrangler.toml

(Cloudflare Docs)

3. 创建并绑定存储

# KV
npx wrangler kv namespace create MY_KV
# D1
npx wrangler d1 create my_db
# R2
npx wrangler r2 bucket create my-bucket

把创建结果（如 namespace/bucket id）写入你的 wrangler 配置后即可在代码里通过绑定访问。(Cloudflare Docs)

4. 管理密钥（不要写进配置文件）

npx wrangler secret put API_KEY

（本地开发还可在项目根加 .dev.vars）(Cloudflare Docs, docs.astro.build)

5. 部署 / 预览

# 直接部署
npx wrangler deploy
# 提交"版本"并生成预览（CI 常用）
npx wrangler versions upload

(Cloudflare Docs)

6. 查看线上日志

npx wrangler tail

(Cloudflare Docs)

---

npm vs npx 有什么区别？

• npm（Node 包管理器）

  • 负责安装/管理依赖 ，比如 npm install wrangler -D 把 wrangler 装进项目的 devDependencies。
  • 也能执行本地项目里的可执行脚本：npm exec wrangler dev（等价于 npx wrangler dev）。(docs.npmjs.com)

• npx（npm 附带的执行器）

  • 用来直接运行一个 npm 包 ，即使它没被全局或本地安装：npx wrangler@latest dev。
  • 适合 一次性运行 最新版本的 CLI，避免全局安装后版本老化；npm v7+ 里也有类似的 npm exec / npm dlx（一次性执行，不写入依赖）。(docs.npmjs.com)

选用建议：

• 想"装一次，团队共享版本 "：用 npm i -D wrangler，再在 package.json 脚本里写 "dev": "wrangler dev"。
• 想"临时用最新 "：用 npx wrangler@latest ... 即开即用。(docs.npmjs.com)

---

迷你备忘单（复制就能用）

# 登录 / 退出
npx wrangler@latest login
npx wrangler@latest logout

# 本地开发（指定配置文件）
npx wrangler@latest dev --config wrangler.jsonc

# 部署 / 版本化预览
npx wrangler@latest deploy
npx wrangler@latest versions upload

# 绑定与资源
npx wrangler@latest kv namespace create MY_KV
npx wrangler@latest d1 create my_db
npx wrangler@latest r2 bucket create my-bucket

# 密钥
npx wrangler@latest secret put API_KEY

# 日志
npx wrangler@latest tail

(Cloudflare Docs)