Wrangler 是 Cloudflare Workers 和 Pages 的官方命令行工具，用于开发、测试和部署 Serverless 应用。
一、 核心安装与登录
在使用 Wrangler 之前，确保已安装 Node.js（建议最低版本为20.18.1）。
npm install -g wrangler
# 登录 Cloudflare 账号（会在浏览器打开授权页面）
wrangler login
# 检查当前登录状态与用户账户信息
wrangler whoami
二、 项目初始化与配置Bash# 创建新的 Cloudflare Workers 或 Pages 项目（交互式引导）：
wrangler init my-project
# 或使用快捷创建命令
npm create cloudflare@latest
初始化后，项目根目录会生成一个 wrangler.toml 文件，这是 Wrangler 的核心配置文件：
Ini, TOMLname = "my-worker"
main = "src/index.js"
compatibility_date = "2024-01-01"
# 绑定 KV 数据库示例
[[kv_namespaces]]
binding = "MY_KV"
id = "xxxxxx"
# 设置环境变量
[vars]
ENVIRONMENT = "production"
三、 本地开发与调试Wrangler 使用 Miniflare 在本地模拟 Cloudflare 运行环境，支持热重载和本地/远程资源调试。
启动本地开发服务器（默认端口 http://localhost:8787）：
wrangler dev
# 启动本地开发并连接到 Cloudflare 真实的远程资源/数据库
wrangler dev --remote
# 指定端口启动
wrangler dev --port 3000
四、 部署与发布Bash# 发布 Worker 到 Cloudflare 线上环境
wrangler deploy
# 部署 Pages 静态网页项目（指定打包目录，如 dist 或 build）
wrangler pages deploy ./dist
# 针对特定环境部署（需在 wrangler.toml 中配置 [env.staging] 等）
wrangler deploy --env staging
五、 核心资源管理指令Cloudflare 提供了多种存储与数据库服务，可以通过 Wrangler 直接在终端操作：
1. KV（键值存储）Bash# 创建 KV 命名空间
wrangler kv:namespace create "MY_KV"
# 写入与获取键值对
wrangler kv:key put --binding=MY_KV "my-key" "my-value"
wrangler kv:key get --binding=MY_KV "my-key"
2. D1（关系型 SQL 数据库）Bash# 创建 D1 数据库
wrangler d1 create my-db
# 执行 SQL 文件（本地测试）
wrangler d1 execute my-db --local --file=./schema.sql
# 执行 SQL 文件（生产环境）
wrangler d1 execute my-db --remote --file=./schema.sql
3. R2（对象存储）Bash# 创建 Bucket
wrangler r2 bucket create my-bucket
# 上传文件
wrangler r2 object put my-bucket/file.png --file=./local-file.png
4. Secrets（机密密钥管理）Bash# 添加加密环境变量（如 API Token，不会明文存入 wrangler.toml）
wrangler secret put API_KEY
# 查看已设置的密钥列表
wrangler secret list
六、 常见实用命令速查
实时日志 wrangler tail 实时查看线上Worker 的 console.log 和报错日志
部署历史 wrangler deployments list 查看历史部署版本
版本回滚 wrangler rollback <deployment-id> 回滚到指定的历史版本
帮助指南 wrangler --help 查看所有指令及参数说明
----------------------------------------
$ wrangler
wrangler
COMMANDS
wrangler docs [search..] 📚 Open Wrangler's command documentation in your browser
wrangler complete [shell] ⌨️ Generate and handle shell completions
wrangler email Manage Cloudflare Email services [open beta]
ACCOUNT
wrangler auth 🔐 Manage authentication
wrangler login 🔓 Login to Cloudflare
wrangler logout 🚪 Logout from Cloudflare
wrangler whoami 🕵️ Retrieve your user information
COMPUTE & AI
wrangler agent-memory 🧠 Manage Agent Memory namespaces [private beta]
wrangler ai 🤖 Manage AI models
wrangler ai-search 🔍 Manage AI Search instances [open beta]
wrangler browser 🌐 Manage Browser Run sessions [open beta]
wrangler containers 📦 Manage Containers
wrangler delete [name] 🗑️ Delete a Worker from Cloudflare
wrangler deploy [path] 🆙 Deploy a Worker to Cloudflare
wrangler deployments 🚢 List and view the current and past deployments for your Worker
wrangler dev [script] 👂 Start a local server for developing your Worker
wrangler dispatch-namespace 🏗️ Manage dispatch namespaces
wrangler flagship 🚩 Manage Flagship apps and feature flags [open beta]
wrangler init [name] 📥 Initialize a basic Worker
wrangler pages ⚡️ Configure Cloudflare Pages
wrangler preview [script] 👀 Create a Preview deployment of the current Worker [open beta]
wrangler queues 📬 Manage Workers Queues
wrangler rollback [version-id] 🔙 Rollback a deployment for a Worker
wrangler secret 🤫 Generate a secret that can be referenced in a Worker
wrangler setup 🪄 Setup a project to work on Cloudflare
wrangler tail [worker] 🦚 Start a log tailing session for a Worker
wrangler triggers 🎯 Updates the triggers of your current deployment [experimental]
wrangler types [path] 📝 Generate types from your Worker configuration
wrangler versions 🫧 List, view, upload and deploy Versions of your Worker to Cloudflare
wrangler vpc 🌐 Manage VPC [open beta]
wrangler workflows 🔁 Manage Workflows
STORAGE & DATABASES
wrangler artifacts 🧱 Manage Artifacts namespaces and repos [private beta]
wrangler d1 🗄️ Manage Workers D1 databases
wrangler hyperdrive 🚀 Manage Hyperdrive databases
wrangler kv 🗂️ Manage Workers KV Namespaces
wrangler pipelines 🚰 Manage Cloudflare Pipelines [open beta]
wrangler r2 📦 Manage R2 buckets & objects
wrangler secrets-store 🔐 Manage the Secrets Store [open beta]
wrangler vectorize 🧮 Manage Vectorize indexes
NETWORKING & SECURITY
wrangler cert 🪪 Manage client mTLS certificates and CA certificate chains used for secured connections [open beta]
wrangler mtls-certificate 🪪 Manage certificates used for mTLS connections
wrangler tunnel 🚇 Manage Cloudflare Tunnels [experimental]
wrangler turnstile 🛡️ Manage Turnstile widgets [alpha]
GLOBAL FLAGS
-c, --config Path to Wrangler configuration file [string]
--cwd Run as if Wrangler was started in the specified directory instead of the current working directory [string]
-e, --env Environment to use for operations, and for selecting .env and .dev.vars files [string]
--env-file Path to an .env file to load - can be specified multiple times - values from earlier files are overridden by values in later files [array]
-h, --help Show help [boolean]
--install-skills Install Cloudflare skills for detected AI coding agents before running the command [boolean] [default: false]
--profile Use a specific auth profile [string]
-v, --version Show version number [boolean]
Please report any issues to https://github.com/cloudflare/workers-sdk/issues/new/choose
----------------
https://developers.cloudflare.com/workers/wrangler/
-----------------------------------------
相关帖子： https://briteming.blogspot.com/2026/09/cloudflare-pages.html
