R2 元数据编辑器

批量更新 Cloudflare R2 对象的缓存控制头和其他元数据。

功能

• ✨ 批量处理 - 一次更新成千上万个文件的元数据
• 🎯 灵活筛选 - 按文件类型、路径前缀筛选
• 🔍 预览模式 - 安全的预览修改，不实际改动文件
• ⚡ 并发处理 - 可配置的并发数，优化处理速度
• 📊 详细日志 - 完整的处理结果统计

快速开始

1. 安装依赖

npm install

2. 配置凭证

复制 .env.example 为 .env：

cp .env.example .env

编辑 .env 文件并填入你的 R2 凭证：

R2_ACCOUNT_ID=your_cloudflare_account_id
R2_ACCESS_KEY=your_r2_access_key
R2_SECRET_KEY=your_r2_secret_key
R2_BUCKET_NAME=your_bucket_name
R2_ENDPOINT=https://your_account_id.r2.cloudflarestorage.com

# 其他可选配置
DRY_RUN=true  # 预览模式（推荐先用 true 预览）
CONCURRENCY=5  # 并发数

3. 获取 R2 凭证

1. 登录 Cloudflare Dashboard
2. 进入 R2
3. 点击 Manage R2 API Tokens
4. 创建新的 API Token（记录访问密钥）
5. 找到你的账户 ID（通常在 URL 中看到）

4. 运行脚本

预览模式（推荐先测试）

npm start

实际修改文件

在 .env 中将 DRY_RUN 改为 false，然后运行：

npm start

更新单个文件

npm run single

编辑 single.js 中的文件key：

updateSingleFile('your-file-name.jpg');

配置选项

环境变量

变量	说明	示例
R2_ACCOUNT_ID	Cloudflare 账户 ID	c8953126a8fbc1bbc4e4a73bab0c89b8
R2_ACCESS_KEY	R2 访问密钥	从 Dashboard 获取
R2_SECRET_KEY	R2 密钥	从 Dashboard 获取
R2_BUCKET_NAME	桶名称	blog
R2_ENDPOINT	R2 端点	https://[account].r2.cloudflarestorage.com
DRY_RUN	预览模式	true / false
CONCURRENCY	并发处理数	5
FILE_TYPES	要处理的文件类型	.jpg,.png,.gif
PREFIX	路径前缀（可选）	images/
CACHE_CONTROL_*	不同文件类型的缓存策略	见下表

缓存控制策略

变量	默认值	说明
CACHE_CONTROL_IMAGES	public, max-age=86400, immutable	图片（1天）
CACHE_CONTROL_CSS	public, max-age=3600	CSS 文件（1小时）
CACHE_CONTROL_JS	public, max-age=3600	JavaScript（1小时）
CACHE_CONTROL_FONTS	public, max-age=86400, immutable	字体（1天）
CACHE_CONTROL_DEFAULT	public, max-age=3600	其他文件（1小时）

使用示例

示例 1：更新所有图片的缓存配置

.env:

DRY_RUN=true
FILE_TYPES=.jpg,.jpeg,.png,.gif,.webp
PREFIX=

示例 2：只更新特定目录的静态资源

.env:

DRY_RUN=true
FILE_TYPES=.js,.css,.woff2
PREFIX=assets/

示例 3：不同文件使用不同缓存策略

.env:

CACHE_CONTROL_IMAGES=public, max-age=31536000, immutable
CACHE_CONTROL_CSS=public, max-age=86400
CACHE_CONTROL_JS=public, max-age=3600

缓存策略说明

• max-age=86400 - 缓存 1 天
• max-age=3600 - 缓存 1 小时
• max-age=31536000 - 缓存 1 年
• immutable - 资源永不变化（适合带版本号的文件）
• public - 所有缓存都可存储（包括代理）

常见问题

Q: 预览模式和实际模式有什么区别？

A: 预览模式（DRY_RUN=true）只显示会做什么修改，不实际修改文件。建议先用预览模式检查配置是否正确。

Q: 如何只处理特定文件夹？

A: 设置 PREFIX 环境变量，例如 PREFIX=images/。

Q: 处理失败了怎么办？

A: 检查以下几点：

1. R2 凭证是否正确
2. 桶名称是否正确
3. 网络连接是否正常
4. API Token 是否有足够权限

Q: 修改后要多久才能生效？

A: 立即生效，但 CDN 节点缓存可能需要 5-10 分钟同步。

Q: 如何验证修改成功？

A: 使用 curl 查看响应头中的缓存信息：

curl -I "https://your-cdn-domain/image.jpg"

安全提示

⚠️ 重要:

• 不要将 .env 文件提交到版本控制
• .gitignore 已包含 .env 规则
• 保管好你的访问密钥，不要泄露给他人
• 定期轮换 API Token

技术细节

• 使用 AWS SDK v3 与 R2 通信（兼容 S3 API）
• 通过 CopyObject 命令更新元数据（原文件内容不变）
• 支持 HTTP/1.1 并发请求
• 自动跳过已配置正确的文件

许可证

MIT

更新日志

v1.0.0

• ✨ 首次发布
• 支持批量更新缓存控制头
• 支持预览模式和实际修改模式
• 灵活的文件筛选选项