命令

所有命令都建议通过 npx wrangler <命令> 调用，这样版本和项目里 package.json 声明的那个一致。

wrangler dev 稳定

在本地起 workerd 运行时。默认监听 127.0.0.1:8787，改文件即热重载。

npx wrangler dev --port 8788 --ip 0.0.0.0

常用 flag：

• --port：本地端口
• --ip：监听地址，容器里要写 0.0.0.0
• --remote：让绑定走远端真实资源，而不是 .wrangler/state 里的本地状态
• --var KEY:value：临时注入变量，不写进配置

wrangler deploy 稳定

构建产物上传并生效。输出包含 Worker 名、版本 ID、触发器和每个绑定的解析结果。

npx wrangler deploy --dry-run

常用 flag：

• --dry-run：只打包校验，不上传、不创建资源
• --outdir <目录>：把最终 bundle 额外写一份到指定目录，方便排查
• --var KEY:value：注入变量
• --secret：配合 wrangler secret put 使用，见下

wrangler login / logout

浏览器 OAuth 授权，token 存在用户配置目录。CI 环境不要用它，改走 CLOUDFLARE_API_TOKEN。

npx wrangler whoami

whoami 会打印当前身份、账号 ID 和 token 的权限范围——排查“为什么这个命令没权限”时先跑它。

wrangler secret

密钥存在平台侧，不进代码也不进 wrangler.jsonc。

npx wrangler secret put MY_TOKEN
npx wrangler secret list
npx wrangler secret delete MY_TOKEN
npx wrangler secret bulk ./secrets.json

wrangler kv

npx wrangler kv namespace create MY_KV
npx wrangler kv key put --namespace-id <id> somekey somevalue
npx wrangler kv key get --namespace-id <id> somekey
npx wrangler kv key list --namespace-id <id>
npx wrangler kv namespace delete --namespace-id <id>

delete 不可撤销

kv namespace delete 直接删整个命名空间和里面所有数据，没有回收站。生产数据请先 key list 导出。

wrangler d1

npx wrangler d1 create todos
npx wrangler d1 execute todos --local --file=./migrations/0001_init.sql
npx wrangler d1 execute todos --remote --command "SELECT * FROM todo LIMIT 5"
npx wrangler d1 migrations list todos --local

--local 和 --remote 是两套独立的数据库，迁移要分别应用。忘了加 --remote 是最常见的“本地好好的线上报错”原因。

wrangler r2

npx wrangler r2 bucket create avatars
npx wrangler r2 object put avatars/logo.png --file=./logo.png
npx wrangler r2 object get avatars/logo.png

wrangler tail

实时看线上日志，NDJSON 输出，可以接 jq。

npx wrangler tail --format json
npx wrangler tail --status error

wrangler types 较新

根据 wrangler.jsonc 里的绑定生成 worker-configuration.d.ts，于是 env.MY_KV 有自动补全，写错绑定名在编辑器里就报红。

npx wrangler types

生成的文件要提交进仓库，并且把它加进 tsconfig.json 的 include。