大型开源文档与电子书的静态资源治理：Git LFS、S3/R2 与 Git 裸存的权衡实践

大家周末好，我是小秦。

最近在协助几个开源知识库和电子书项目（主要是基于 VitePress 和 mdBook 搭建）做归档重构，发现随着配图、架构图源文件（如 .drawio）以及示例附件的增多，静态资源治理成了一个绕不开的坎。

梳理了一下目前社区常见的几套方案，感觉各有利弊：

1. Git 裸存（Direct Git Commit）

   • 优势：心智负担最低，文本与资源严格版本对齐，本地离线写作与预览体验极佳。
   • 痛点：仓库体积膨胀是单向不可逆的，长期来看对 CI/CD 拉取和初次参与贡献的开发者非常不友好。

2. Git LFS

   • 优势：保留了 Git 原生工作流，大文件按需下载。
   • 痛点：对第三方贡献者有额外配置成本；且在 GitHub 等平台对 Fork 仓库、LFS 带宽与存储配额有较多限制，偶尔会出现“配额耗尽导致构建挂掉”的尴尬情况。

3. 外部对象存储（如 Cloudflare R2 / AWS S3 + 自动图床）

   • 优势：Git 仓库保持纯粹的代码/文本状态，极其轻量；结合自动化 Action 上传也很省心。
   • 痛点：静态资源与文档版本解耦，历史版本回溯和预览难度变大，且完全丧失了单机离线完整构建的能力。

像 Kubernetes 官方文档（k8s.io）早期也经历过把二进制资源外移的痛苦演进；而很多独立技术书作者为了降低协作门槛，最终又妥协回了 Git 裸存。

想向各位常年维护大型文档、开源电子书的朋友请教： 大家目前更倾向于哪种方案？在保证外部贡献者体验（Low barrier to contribute）和仓库体积长期健康之间，你们找到了怎样的折中点？