文档站的截图和示例工程都塞进 Git 仓库后,我把素材托管重新理了一遍

2 阅读7分钟

一、起因:帮助中心的素材,我一开始全塞进了文档仓库

前段时间我给自己的小工具做了一个帮助中心,用的是静态文档生成器,正文全是 Markdown,提交到仓库后由 CI 构建发布。

刚开始内容少,我顺手把所有素材都放进了文档仓库:操作截图放在静态资源目录,随站点一起打包;几个示例工程压缩包、一份 PDF 速查卡、一个安装包,也都直接丢进仓库里,需要的时候在文档里写相对路径引用。

那时候我觉得这样最省心——素材和文档在一起,clone 下来什么都有,不依赖任何外部服务。直到截图和附件越攒越多,问题才一点点冒出来。

二、问题先在仓库体积和构建速度上冒出来

帮助中心的特点是截图特别多:每个功能都要配操作步骤图,界面一改版,截图还得重新截。我先注意到的是仓库越来越大。

我用 du 看了一下本地目录的体积构成,发现占大头的不是正文,而是 .git 目录。原因不难理解:

  • 文本可以增量存储。Markdown 改一行,Git 只记录这一行的差异,历史版本很轻。
  • 二进制图片是全量存储。一张截图哪怕只改了一个角,Git 也没法 diff,只能把整张图重新存一份。截图反复替换,历史里就摞了一堆完整的图片文件。
  • 附件更夸张。示例工程压缩包、安装包这类文件本身就大,每更新一次,仓库就再背一份,clone 和拉取明显变慢,CI 构建也要花更多时间搬运这些文件。

我把这两类内容在版本管理上的差异整理成了一张表:

对比项Markdown 正文截图 / 附件
能否逐行 diff能,改动清晰不能,二进制无法比较
每次提交的体积只存差异,很小基本全量存储
频繁改动的影响历史依然轻历史快速膨胀
适合的管理方式进 Git 版本管理独立托管、用链接引用

排查到这里,我意识到自己把两种性质完全不同的东西,硬塞进了同一种管理方式。

三、想明白一件事:文档内容和素材应该分开管

静态文档站真正需要 Git 来管理的,是文字内容:章节结构、说明文字、配置项,这些要靠分支、合并、回滚来协作,进 Git 天经地义。

而截图和附件本质上是被引用的资源,它们不需要跟着每一次文档提交进历史,更适合放到一个独立的地方统一托管,文档里只保留一条链接。

想清楚这点,我定下了一个原则:文本进 Git,素材走独立托管,文档里只引用链接。这样仓库始终保持轻量,素材的增删改也不会再污染提交历史。

四、配图怎么安排:统一托管、按栏目分目录、拿链接贴进去

我把帮助中心里所有截图收拢到一起,按文档栏目建了多级目录,比如「入门」「进阶配置」「常见问题」各占一个目录,服务端还会在路径里叠加随机串,避免不同文章里同名文件互相冲突。

具体做法是这样的:

  1. 先传图、再写文档。截图上传后直接取 Markdown 格式的链接,粘到正文对应位置就是一张图,不用手写路径。
  2. 按场景取不同版本。正文里用压缩后的图保证页面加载轻快;遇到需要看清细节的配置项,就再放一个指向原图的链接,让读者点开看高清版本。
  3. 改版用同名覆盖。界面调整后,我用同样的文件名重新上传截图,链接保持不变,文档里的引用一个字都不用改。这种同名覆盖的用法我在一篇文档改版的记录里也写过,在帮助中心这种反复改版的场景下特别省心。
  4. 确认外链是公开稳定的。帮助中心对所有访客开放,配图必须能被任何人直接打开,不能带会过期的临时签名,也不能触发防盗链把读者挡在外面。我会用无痕窗口打开文档,确认每张图都正常加载。

五、附件怎么安排:给 PDF、压缩包、安装包一个能直接下载的链接

文档里除了图,还有一类是供下载的附件,这部分我也从仓库里挪了出来。

  • 示例工程压缩包、安装包、PDF 速查卡统一托管,文档里放一条可直接下载的直链,读者点一下就能下载,不再占用文档仓库的体积。
  • 是在线预览还是直接下载,取决于返回的响应头,这套机制我在之前一篇讲文件直链的文章里详细拆过,这里就不重复了。
  • 个别可以直接在浏览器里看的内容,比如 HTML 格式的示例,托管后能直接打开预览,不用先下载再本地打开。
  • 上传大文件时我会留意平台的单文件大小上限,避免传到一半才发现超限。

附件独立托管还有个好处:安装包升级时,我只需要替换托管处的文件、更新下载链接,文档正文和仓库都不用动,发布节奏完全解耦。

六、工具无关的一段:我自己的选择

需要说明的是,上面这套做法并不绑定某一家服务。自己开对象存储、配好分发,或者用任何一个能提供稳定公开外链、支持多格式输出和多级目录的托管服务,这套流程都能跑通。

我个人图省事,没有单独去维护一套存储,把截图和附件放在了图床小镇,纯粹是用顺手了、省得自己折腾配置;换成具备同样条件的服务,结论完全一样,这只是个人选择,并不是唯一答案。

七、固定下来的流程和上线自检

经过这次调整,我把文档站的素材管理固定成了下面这套流程:

  1. 写文档前,先把这一篇要用到的截图、附件统一上传,按栏目放进对应目录。
  2. 配图取 Markdown 链接贴进正文,附件取可直接下载的直链。
  3. 仓库里只提交 Markdown 正文和必要配置,保持仓库轻量。
  4. 改版截图用同名覆盖,不新增文件名、不改文档引用。
  5. 文档站换框架或迁移时,因为图片附件都是完整外链,正文搬过去链接照样有效,不用重新排素材路径。

每次发布前,我还会按这份清单自检:

  • 无痕窗口打开,所有配图都能正常加载、没有裂图
  • 附件链接点击能正常下载或预览,没有跳转到登录页
  • 外链是长期稳定地址,不依赖会过期的临时签名
  • 仓库里没有残留大体积二进制文件,提交历史保持干净
  • 手机和电脑分别打开一次,确认多端显示正常

整套调整做完,最直观的变化是文档仓库重新瘦了下来,clone 和 CI 都快了不少;而帮助中心该有的图、该下载的附件,读者那边一个都没少。

如果你也在一个人维护产品文档或帮助中心,不妨先把「内容」和「素材」分开看,思路会清晰很多。

官网:imgbed.cn