【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)
典型工作流（上手就用）
- 登录
npx wrangler@latest login
- 本地开发
npx wrangler@latest dev
（需要特定配置文件时）
npx wrangler@latest dev --config wrangler.toml
(Cloudflare Docs)
- 创建并绑定存储
# 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)
- 管理密钥（不要写进配置文件）
npx wrangler secret put API_KEY
（本地开发还可在项目根加 .dev.vars）(Cloudflare Docs, docs.astro.build)
- 部署 / 预览
# 直接部署
npx wrangler deploy
# 提交“版本”并生成预览（CI 常用）
npx wrangler versions upload
(Cloudflare Docs)
- 查看线上日志
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 包，即使它没被全局或本地安装：
选用建议：
- 想“装一次，团队共享版本”：用
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)