[!info] related notes

• 相关资源: Cloudflare, Cloudflare Workers AI Vision
• 应用场景: 视频素材理解管线

Wrangler

这是什么

Wrangler 是 Cloudflare 官方的命令行工具，用于在本地开发、测试和部署 Cloudflare Workers 和 Pages 项目。类似于 Docker 的 docker CLI 或 Netlify 的 netlify CLI。

安装

需要 Node.js 环境。

# 全局安装
npm install -g wrangler

# 或者用 npx 免安装运行
npx wrangler --version

也可以通过 create-cloudflare CLI 创建项目时自动引入：

npm create cloudflare@latest my-project

核心命令

登录认证

wrangler login

在浏览器中完成 Cloudflare 账号授权。登录后 token 保存在本地，后续命令自动使用。

# 查看当前登录状态
wrangler whoami

# 登出
wrangler logout

本地开发

wrangler dev

在本地启动 Worker 开发服务器，默认监听 http://localhost:8787。支持热重载，修改代码后自动刷新。

支持的参数：

# 指定端口
wrangler dev --port 9000

# 使用远程绑定（如 Workers AI、KV、D1）
wrangler dev --remote

注意：Workers AI 等需要远程资源的 binding，本地开发时需要加 --remote 才能正常调用。

部署

wrangler deploy

将 Worker 部署到 Cloudflare 全球网络。部署成功后返回 Worker 的 URL：

https://my-worker.xxxx.workers.dev

项目初始化

# 创建新项目
npm create cloudflare@latest my-project

# 或在已有目录中初始化
wrangler init

配置文件 wrangler.toml

Worker 项目的根目录下有一个 wrangler.toml，定义项目的名称、入口、兼容性和绑定。

最小配置

name = "my-worker"
main = "src/index.ts"
compatibility_date = "2026-06-09"

绑定 Workers AI

[ai]
binding = "AI"

绑定后在代码中通过 env.AI 访问：

export interface Env {
  AI: Ai;
}

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const result = await env.AI.run(
      "@cf/meta/llama-3.2-11b-vision-instruct",
      { messages: [...], image: "base64..." }
    );
    return Response.json(result);
  }
} satisfies ExportedHandler<Env>;

绑定其他资源

# KV 命名空间
[[kv_namespaces]]
binding = "CACHE"
id = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# D1 数据库
[[d1_databases]]
binding = "DB"
database_name = "my-db"
database_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

# R2 存储桶
[[r2_buckets]]
binding = "STORAGE"
bucket_name = "my-bucket"

项目结构

典型 Worker 项目结构：

my-worker/
├── wrangler.toml          # 项目配置
├── package.json
├── src/
│   └── index.ts           # Worker 入口
└── node_modules/

环境变量与 Secrets

# 环境变量（明文，写在 toml 里）
[vars]
API_URL = "https://api.example.com"

# Secrets（加密存储，通过命令行设置）
# wrangler secret put MY_SECRET

# 设置 secret
wrangler secret put API_KEY

# 列出 secrets
wrangler secret list

# 删除 secret
wrangler secret delete API_KEY

常用调试技巧

# 查看实时日志
wrangler tail

# 查看 Worker 部署历史
wrangler deployments list

# 回滚到上一个版本
wrangler rollback

与 Cloudflare Dashboard 的关系

• Wrangler 适合开发者本地工作流（代码 → 测试 → 部署）
• Dashboard 适合在线查看日志、监控、配置管理
• 两者操作的是同一套资源，互相同步

相关链接

• Wrangler 官方文档
• create-cloudflare 文档
• wrangler.toml 配置参考

Related notes

• Cloudflare
• Cloudflare Workers AI Vision
• 视频素材理解管线