Cloudflare Wrangler CLI 备忘

Wrangler 是 Cloudflare Workers 的官方命令行工具，用于开发、测试和部署 Serverless 应用。本文档涵盖常用命令和最佳实践。

安装与配置

使用 npx（推荐）

无需全局安装，直接使用 npx 调用：

npx wrangler <command>

优势：

始终使用项目依赖中的 wrangler 版本
避免全局版本冲突
团队协作时版本一致

全局安装

npm install -g wrangler

登录认证

npx wrangler login

执行后会打开浏览器，完成 Cloudflare 账户授权。

D1 数据库管理

D1 是 Cloudflare 提供的 Serverless SQLite 数据库。

创建数据库

npx wrangler d1 create <database-name>

输出示例：

✅ Successfully created DB 'my-database'
binding = "DB"
database_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

将输出的配置添加到 wrangler.jsonc：

{
  "d1_databases": [
    {
      "binding": "DB",
      "database_name": "my-database",
      "database_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    }
  ]
}

执行 SQL 文件

本地环境：

npx wrangler d1 execute <database-name> --local --file=schema.sql

远程环境（生产）：

npx wrangler d1 execute <database-name> --remote --file=schema.sql

执行 SQL 命令

npx wrangler d1 execute <database-name> --remote --command="SELECT * FROM users LIMIT 10;"

执行多条语句：

npx wrangler d1 execute <database-name> --remote --command="
  INSERT INTO users (id, name) VALUES ('1', 'Alice');
  INSERT INTO users (id, name) VALUES ('2', 'Bob');
"

导出数据库

npx wrangler d1 export <database-name> --remote --output=backup.sql

用途：

数据备份
迁移数据到其他环境
审查数据库结构

查看数据库列表

npx wrangler d1 list

删除数据库

npx wrangler d1 delete <database-name>

注意： 此操作不可逆，请谨慎使用。

R2 对象存储

R2 是 Cloudflare 的对象存储服务，兼容 S3 API。

创建存储桶

npx wrangler r2 bucket create <bucket-name>

配置到 wrangler.jsonc：

{
  "r2_buckets": [
    {
      "binding": "BUCKET",
      "bucket_name": "my-bucket"
    }
  ]
}

列出所有存储桶

npx wrangler r2 bucket list

查看存储桶信息

npx wrangler r2 bucket info <bucket-name>

列出存储桶中的对象

Wrangler CLI 不支持直接列出对象，需要通过以下方式：

方法 1: 通过 Cloudflare Dashboard

登录 Dashboard
进入 R2 > 选择存储桶
在 Objects 标签页查看所有对象

方法 2: 通过 Worker 代码

// 在 Worker 中列出对象
const { objects } = await env.BUCKET.list({
  limit: 100,           // 可选，默认 1000
  prefix: 'folder/',    // 可选，按前缀过滤
  delimiter: '/',       // 可选，按分隔符过滤
  cursor: undefined     // 可选，分页游标
});

for (const obj of objects) {
  console.log(obj.key, obj.size, obj.uploaded);
}

方法 3: 使用 S3 兼容工具

R2 兼容 S3 API，可以使用 AWS CLI：

# 配置 AWS CLI（使用 R2 的 API Token）
aws configure --profile r2

# 列出对象
aws s3 ls s3://<bucket-name> --endpoint-url=https://<account-id>.r2.cloudflarestorage.com --profile r2

上传对象

npx wrangler r2 object put <bucket-name>/path/to/file.jpg --file=./local/file.jpg

下载对象

npx wrangler r2 object get <bucket-name>/path/to/file.jpg --file=./downloaded.jpg

删除对象

npx wrangler r2 object delete <bucket-name>/path/to/file.jpg

删除存储桶

npx wrangler r2 bucket delete <bucket-name>

注意： 存储桶必须为空才能删除。

对象生命周期管理

R2 支持配置生命周期规则，自动删除过期对象。生命周期规则通过 Dashboard 或 API 配置。

方法 1: 通过 Cloudflare Dashboard 配置

登录 Cloudflare Dashboard
进入 R2 > 选择存储桶
点击 Settings 标签页
在 Object lifecycle rules 部分点击 Add rule
配置规则：
- Rule name: 自定义规则名称（如 "Delete after 30 days"）
- Prefix: 可选，只影响特定前缀的对象（如 temp/）
- Days after upload: 对象上传后多少天删除（如 30）

方法 2: 通过代码设置对象元数据

在上传对象时设置自定义元数据，然后通过定时任务清理：

// 上传时设置过期时间戳
await env.BUCKET.put('temp/file.jpg', fileData, {
  customMetadata: {
    expiresAt: String(Date.now() + 30 * 24 * 60 * 60 * 1000) // 30 天后
  }
});

// 在 Cron 任务中清理过期对象
export default {
  async scheduled(event: ScheduledEvent, env: Env) {
    const { objects } = await env.BUCKET.list({ prefix: 'temp/' });

    for (const obj of objects) {
      const metadata = await env.BUCKET.head(obj.key);
      const expiresAt = metadata?.customMetadata?.expiresAt;

      if (expiresAt && Date.now() > parseInt(expiresAt)) {
        await env.BUCKET.delete(obj.key);
        console.log(`Deleted expired object: ${obj.key}`);
      }
    }
  }
}

方法 3: 使用 HTTP Headers (Cache-Control)

虽然 R2 不直接支持 S3 的 Lifecycle policies，但可以通过 httpMetadata 设置缓存控制：

await env.BUCKET.put('file.jpg', fileData, {
  httpMetadata: {
    cacheControl: 'max-age=2592000' // 30 天缓存
  }
});

注意： Cache-Control 只影响 CDN 缓存，不会自动删除 R2 中的对象。

常见生命周期策略

场景	配置
临时文件（7 天）	Days after upload: 7
日志文件（30 天）	Prefix: `logs/`, Days: 30
缓存文件（24 小时）	使用代码定时清理
用户上传（90 天）	Days after upload: 90

最佳实践

使用前缀区分：将临时文件和永久文件分开存储

/temp/       → 7 天自动删除
/permanent/  → 不设置生命周期
/logs/       → 30 天自动删除

监控删除日志：在 Worker 中记录删除操作

console.log(`Lifecycle deleted: ${deletedCount} objects`);

测试规则：先在测试存储桶验证规则，再应用到生产环境

环境变量与密钥

Secret（加密密钥）

设置 Secret：

npx wrangler secret put API_KEY

执行后会提示输入密钥值：

Enter a secret value: ****************

列出所有 Secrets：

npx wrangler secret list

删除 Secret：

npx wrangler secret delete API_KEY

本地开发环境变量

创建 .dev.vars 文件（不要提交到 Git）：

API_KEY=your-api-key-here
DATABASE_URL=sqlite://local.db
DEBUG=true

在 .gitignore 中排除：

.dev.vars

在代码中访问

export default {
  async fetch(request: Request, env: Env) {
    const apiKey = env.API_KEY;  // 读取 Secret 或环境变量
    // ...
  }
}

开发与部署

本地开发

npx wrangler dev

指定端口：

npx wrangler dev --port=3000

启用远程模式（使用生产 D1/R2）：

npx wrangler dev --remote

部署到生产环境

npx wrangler deploy

部署特定入口文件：

npx wrangler deploy src/index.ts

查看部署历史

npx wrangler deployments list

输出示例：

Deployment ID: xxxxxx
Created:       2025-12-28 10:30:00
Author:        user@example.com

回滚到上一个版本

npx wrangler rollback

回滚到特定版本：

npx wrangler rollback --deployment-id=xxxxxx

定时任务 (Cron Triggers)

配置 Cron 触发器

在 wrangler.jsonc 中添加：

{
  "triggers": {
    "crons": [
      "0 0 * * *",    // 每天 UTC 00:00
      "*/15 * * * *"  // 每 15 分钟
    ]
  }
}

Cron 表达式格式

┌─────────── 分钟 (0-59)
│ ┌───────── 小时 (0-23)
│ │ ┌─────── 日期 (1-31)
│ │ │ ┌───── 月份 (1-12)
│ │ │ │ ┌─── 星期 (0-7, 0 和 7 都代表周日)
│ │ │ │ │
* * * * *

常用示例：

0 0 * * * - 每天午夜
0 */6 * * * - 每 6 小时
0 0 * * 1 - 每周一午夜
0 0 1 * * - 每月 1 号午夜

处理 Cron 事件

export default {
  async scheduled(event: ScheduledEvent, env: Env, ctx: ExecutionContext) {
    console.log('Cron job triggered at:', new Date(event.scheduledTime));

    // 执行定时任务
    await performScheduledTask(env);
  }
}

测试 Cron 触发器（本地）

curl "http://localhost:8787/__scheduled?cron=0+0+*+*+*"

查看触发器列表

npx wrangler triggers list

日志与监控

实时日志

npx wrangler tail

按状态过滤：

npx wrangler tail --status=error

按请求方法过滤：

npx wrangler tail --method=POST

查看最近的日志

npx wrangler tail --format=pretty

最佳实践

1. 环境隔离

开发环境：

使用 --local 标志
数据存储在 .wrangler/state/ 目录
环境变量在 .dev.vars 文件中

生产环境：

使用 --remote 标志
通过 wrangler secret put 设置密钥
始终先备份再操作

2. 数据库迁移

# 1. 导出当前生产数据
npx wrangler d1 export my-db --remote --output=backup_$(date +%Y%m%d).sql

# 2. 应用新的 schema
npx wrangler d1 execute my-db --remote --file=migrations/001_add_column.sql

# 3. 验证
npx wrangler d1 execute my-db --remote --command="PRAGMA table_info(users);"

3. 部署前检查清单

本地测试通过 (npx wrangler dev)
代码通过 Lint 和类型检查
数据库 Schema 已同步到远程
所有 Secrets 已配置
回滚计划已准备

4. 版本控制

wrangler.jsonc 示例：

{
  "name": "my-worker",
  "main": "src/index.ts",
  "compatibility_date": "2025-01-01",
  "compatibility_flags": ["nodejs_compat"]
}

重要配置：

compatibility_date: 锁定 Workers 运行时行为
compatibility_flags: 启用特定功能（如 Node.js 兼容）

5. 监控和告警

export default {
  async fetch(request: Request, env: Env, ctx: ExecutionContext) {
    const start = Date.now();

    try {
      const response = await handleRequest(request, env);

      // 记录性能指标
      const duration = Date.now() - start;
      console.log(`Request processed in ${duration}ms`);

      return response;
    } catch (error) {
      // 记录错误
      console.error('Request failed:', error);

      // 可以集成第三方监控服务（如 Sentry）
      // await reportError(error, env);

      return new Response('Internal Server Error', { status: 500 });
    }
  }
}

6. 常用命令别名

在 package.json 中添加脚本：

{
  "scripts": {
    "dev": "wrangler dev",
    "deploy": "wrangler deploy",
    "tail": "wrangler tail",
    "db:local": "wrangler d1 execute my-db --local --file=schema.sql",
    "db:remote": "wrangler d1 execute my-db --remote --file=schema.sql"
  }
}

使用：

npm run dev
npm run deploy

故障排查

问题 1: 本地数据库找不到

症状： Error: no such table: users

解决：

npx wrangler d1 execute my-db --local --file=schema.sql

问题 2: Secret 未生效

症状： env.API_KEY is undefined

解决：

生产环境：npx wrangler secret put API_KEY
本地环境：检查 .dev.vars 文件是否存在

问题 3: 部署后代码未更新

解决：

清除浏览器缓存（Ctrl+F5）
检查部署日志：npx wrangler deployments list
查看实时日志：npx wrangler tail

问题 4: Cron 任务未触发

排查：

检查 wrangler.jsonc 中的 cron 表达式
确认已部署到生产环境（本地不支持 cron）
查看日志：npx wrangler tail

参考资源

总结

Wrangler 是开发 Cloudflare Workers 应用的核心工具。掌握以下核心命令即可覆盖大部分场景：

功能	命令
本地开发	`npx wrangler dev`
部署	`npx wrangler deploy`
数据库操作	`npx wrangler d1 execute <db> --remote --file=schema.sql`
配置密钥	`npx wrangler secret put <KEY>`
查看日志	`npx wrangler tail`
导出数据	`npx wrangler d1 export <db> --remote --output=backup.sql`

建议在项目中保留一份简化的命令速查表，方便团队成员快速上手。

posted @ 2025-12-28 14:32 LexLuc 阅读(22) 评论(0) 收藏举报

刷新页面返回顶部

Lex个人随想乡

Attention before pay attention

Cloudflare Wrangler CLI 备忘

目录

安装与配置

使用 npx（推荐）

全局安装

登录认证

D1 数据库管理

创建数据库

执行 SQL 文件

执行 SQL 命令

导出数据库

查看数据库列表

删除数据库

R2 对象存储

创建存储桶

列出所有存储桶

查看存储桶信息

列出存储桶中的对象

上传对象

下载对象

删除对象

删除存储桶

对象生命周期管理

方法 1: 通过 Cloudflare Dashboard 配置

方法 2: 通过代码设置对象元数据

方法 3: 使用 HTTP Headers (Cache-Control)

常见生命周期策略

最佳实践

环境变量与密钥

Secret（加密密钥）

本地开发环境变量

在代码中访问

开发与部署

本地开发

部署到生产环境

查看部署历史

回滚到上一个版本

定时任务 (Cron Triggers)

配置 Cron 触发器

Cron 表达式格式

处理 Cron 事件

测试 Cron 触发器（本地）

查看触发器列表

日志与监控

实时日志

查看最近的日志

最佳实践

1. 环境隔离

2. 数据库迁移

3. 部署前检查清单

4. 版本控制

5. 监控和告警

6. 常用命令别名

故障排查

问题 1: 本地数据库找不到

问题 2: Secret 未生效

问题 3: 部署后代码未更新

问题 4: Cron 任务未触发

参考资源

总结