部署 Afilmory 相册：在 Cloudflare 上的踩坑与终极配置
最近准备把 Afilmory 相册部署到 Cloudflare 上。本来以为 Fork 完官方仓库、连上后台就能直接一键上线，结果中间遭遇了子模块拉取失败、S3 环境变量无法读取、Wrangler 部署命令工作区冲突等一系列怪事。
折腾了大半天，把原委和底层的依赖关系摸透了。这项目虽然结构是 Monorepo（多包仓库），但如果要部署个人相册前端，千万不要去走 Workers 和 Wrangler 部署指令，直接用 Cloudflare Pages 静态托管才是最干净、最省心的方案。
为什么放弃 Workers 走 Pages？
Afilmory 的核心前端是一个 Vite + PWA 的静态相册，在构建时通过 @afilmory/builder 去你的 R2/S3 存储桶抓取照片信息并生成 JSON 清单，编译出来的产物全是纯静态文件。
一开始我在部署指令里写了 npx wrangler deploy 或者想指定子工作区去发版，结果系统一遇上多包仓库就会误判：
- 要么报错提示命令跑在了根工作区（
in the root of a workspace） - 要么把仓库里别的依赖（比如后端目录的
next.config.mjs）扫出来，误以为你要部署一个 Next.js 项目，自动触发依赖迁移脚本，再被 pnpm 策略拦截。
对个人相册来说，直接让 Cloudflare Pages 跑完构建、自动托管静态输出目录就够了，完全不需要写任何单独的 deploy 命令。
核心部署步骤
在 Cloudflare 面板进入 Workers & Pages -> Create application -> Pages，关联你 Fork 下来的 Afilmory 仓库。
构建设置需要精简成下面这样：
| 设置项 | 正确配置值 | 说明 |
|---|---|---|
| 构建命令 (Build command) | pnpm run build | 构建时会自动读取存储桶生成图片清单 |
| 构建输出目录 (Build output directory) | apps/web/dist | Vite 编译后的静态网页最终存放地 |
| 根目录 (Root directory) | 留空 (或写 /) | 必须从最外层读取根依赖 |
| 部署命令 (Deploy command) | 留空 | Pages 会自动发版，填任何命令都会重复引发冲突 |
环境变量与机密配置
构筑个人相册的核心，在于让构建脚本读对 R2 存储桶的信息。需要在项目的 Settings -> Environment variables 中，将生产环境和预览环境同时补齐以下关键参数：
| 变量名 | 推荐填入值 | 作用解释 |
|---|---|---|
STORAGE_TYPE | s3 | 使用 S3 / R2 兼容模式 |
S3_BUCKET | afilmory | 供 @afilmory/builder 在打包构建时抓取清单使用 |
S3_BUCKET_NAME | afilmory | 供 apps/web 前端运行时页面校验使用 |
S3_REGION | auto | Cloudflare R2 固定写 auto |
S3_ENDPOINT | https://<账号ID>.r2.cloudflarestorage.com | R2 存储桶的 S3 兼容 API 地址 |
S3_ACCESS_KEY_ID | 你的 Access Key ID | 访问密钥 ID |
S3_SECRET_ACCESS_KEY | 你的完整 Secret Key | 访问密钥凭据，建议设为 Encrypt (加密) |
GIT_SUBMODULES | false | 禁止构建时递归拉取 Git 子模块 |
NODE_VERSION | 22 | 指定 Node.js 版本，保证 pnpm v11 正常运行 |
避坑记录
1. 为什么构建一直报 S3 bucket is required？
这是整个项目最容易卡住的地方。官方包里构建脚本和运行时页面的变量作用域有割裂：
- 负责生成照片清单的
@afilmory/builder构建包，读取的是S3_BUCKET - 而网页运行时很多逻辑去校验的是
S3_BUCKET_NAME
只填一个就会在不同阶段触发桶名为空的致命报错，必须把这两个变量同时添上，并且让值保持一致。
2. Fork 后的 Git 子模块拉取异常
刚 Fork 的仓库如果直接部署，构建最前期的 Cloning repository... 阶段很经常报 error occurred while updating repository submodules。 原因是上游原版仓库带有 .gitmodules 配置文件，通常指向作者原本的私有库或示例照片源。不需要再去终端里手动清 Git 树，只需在环境变量里加一句 GIT_SUBMODULES = false 就能屏蔽掉。
3. 修改完环境变量不要直接重试
如果在面板里刚刚补齐了缺失的环境变量，千万不要直接点构建行最右侧的 Retry deployment。单纯重试有概率会直接复用上次未生效的旧环境变量快照。 最稳妥的做法是点击 Clear cache and deploy (清除缓存并部署)，让编译容器全量重走一遍参数注入。
总结
对基于 Monorepo 的前端工程，如果最终目标只是发布静态页，尽量别用命令行强行发版去挑战部署工具的智能判断。把构建逻辑留给 pnpm run build，把分发交给 Pages 的输出目录自动捕捉，反而能省很多无效调试的时间。