从本地脚本到 R2：上传、缓存与内容数据闭环

三档图片生成后，剩下的问题是：怎么让网页稳定拿到它们。

这一步我没有做后台管理页，也没有把上传能力暴露成 API。原因很简单：这是个人站，写权限应该只留在本地 .env.local 和脚本里。

上传用 S3 API

Cloudflare R2 兼容 S3 API，所以脚本直接用 @aws-sdk/client-s3。关键配置来自 .env.local：

• R2_ACCOUNT_ID
• R2_BUCKET
• R2_ACCESS_KEY_ID
• R2_SECRET_ACCESS_KEY
• R2_PUBLIC_BASE_URL
• R2_PHOTOS_PREFIX

上传时给每个 WebP 设置：

CacheControl: "public, max-age=31536000, immutable"

图片 key 一旦生成就尽量不改，浏览器和 CDN 就可以放心长期缓存。

manifest 是中间账本

处理脚本会记录本地路径、R2 key、公开 URL、宽高、EXIF、文件大小和上传时间。这个 manifest 像一本账：处理、上传、生成内容数据都围着它走。

有了它，后续脚本不需要重新猜图片在哪里，也不需要重新解析一次所有原图。

YAML 是页面的入口

最后一步是 pnpm photos:generate，把 manifest 转成 content/gallery/*.yaml。Velite 读取 YAML 后，页面就得到类型安全的摄影数据。

这样前端只需要处理"展示照片"，而不是处理"照片如何被处理、上传、命名、缓存"。

心得

这次最大的收获是边界感：本地脚本负责写权限和重计算，R2 负责静态资产，YAML 负责内容入口，页面负责渲染。每一层都很小，但连起来就变成了一条稳定的发布路径。