一、起因:帮助中心的素材,我一开始全塞进了文档仓库
前段时间我给自己的小工具做了一个帮助中心,用的是静态文档生成器,正文全是 Markdown,提交到仓库后由 CI 构建发布。
刚开始内容少,我顺手把所有素材都放进了文档仓库:操作截图放在静态资源目录,随站点一起打包;几个示例工程压缩包、一份 PDF 速查卡、一个安装包,也都直接丢进仓库里,需要的时候在文档里写相对路径引用。
那时候我觉得这样最省心——素材和文档在一起,clone 下来什么都有,不依赖任何外部服务。直到截图和附件越攒越多,问题才一点点冒出来。
二、问题先在仓库体积和构建速度上冒出来
帮助中心的特点是截图特别多:每个功能都要配操作步骤图,界面一改版,截图还得重新截。我先注意到的是仓库越来越大。
我用 du 看了一下本地目录的体积构成,发现占大头的不是正文,而是 .git 目录。原因不难理解:
- 文本可以增量存储。Markdown 改一行,Git 只记录这一行的差异,历史版本很轻。
- 二进制图片是全量存储。一张截图哪怕只改了一个角,Git 也没法 diff,只能把整张图重新存一份。截图反复替换,历史里就摞了一堆完整的图片文件。
- 附件更夸张。示例工程压缩包、安装包这类文件本身就大,每更新一次,仓库就再背一份,clone 和拉取明显变慢,CI 构建也要花更多时间搬运这些文件。
我把这两类内容在版本管理上的差异整理成了一张表:
| 对比项 | Markdown 正文 | 截图 / 附件 |
|---|---|---|
| 能否逐行 diff | 能,改动清晰 | 不能,二进制无法比较 |
| 每次提交的体积 | 只存差异,很小 | 基本全量存储 |
| 频繁改动的影响 | 历史依然轻 | 历史快速膨胀 |
| 适合的管理方式 | 进 Git 版本管理 | 独立托管、用链接引用 |
排查到这里,我意识到自己把两种性质完全不同的东西,硬塞进了同一种管理方式。
三、想明白一件事:文档内容和素材应该分开管
静态文档站真正需要 Git 来管理的,是文字内容:章节结构、说明文字、配置项,这些要靠分支、合并、回滚来协作,进 Git 天经地义。
而截图和附件本质上是被引用的资源,它们不需要跟着每一次文档提交进历史,更适合放到一个独立的地方统一托管,文档里只保留一条链接。
想清楚这点,我定下了一个原则:文本进 Git,素材走独立托管,文档里只引用链接。这样仓库始终保持轻量,素材的增删改也不会再污染提交历史。
四、配图怎么安排:统一托管、按栏目分目录、拿链接贴进去
我把帮助中心里所有截图收拢到一起,按文档栏目建了多级目录,比如「入门」「进阶配置」「常见问题」各占一个目录,服务端还会在路径里叠加随机串,避免不同文章里同名文件互相冲突。
具体做法是这样的:
- 先传图、再写文档。截图上传后直接取 Markdown 格式的链接,粘到正文对应位置就是一张图,不用手写路径。
- 按场景取不同版本。正文里用压缩后的图保证页面加载轻快;遇到需要看清细节的配置项,就再放一个指向原图的链接,让读者点开看高清版本。
- 改版用同名覆盖。界面调整后,我用同样的文件名重新上传截图,链接保持不变,文档里的引用一个字都不用改。这种同名覆盖的用法我在一篇文档改版的记录里也写过,在帮助中心这种反复改版的场景下特别省心。
- 确认外链是公开稳定的。帮助中心对所有访客开放,配图必须能被任何人直接打开,不能带会过期的临时签名,也不能触发防盗链把读者挡在外面。我会用无痕窗口打开文档,确认每张图都正常加载。
五、附件怎么安排:给 PDF、压缩包、安装包一个能直接下载的链接
文档里除了图,还有一类是供下载的附件,这部分我也从仓库里挪了出来。
- 示例工程压缩包、安装包、PDF 速查卡统一托管,文档里放一条可直接下载的直链,读者点一下就能下载,不再占用文档仓库的体积。
- 是在线预览还是直接下载,取决于返回的响应头,这套机制我在之前一篇讲文件直链的文章里详细拆过,这里就不重复了。
- 个别可以直接在浏览器里看的内容,比如 HTML 格式的示例,托管后能直接打开预览,不用先下载再本地打开。
- 上传大文件时我会留意平台的单文件大小上限,避免传到一半才发现超限。
附件独立托管还有个好处:安装包升级时,我只需要替换托管处的文件、更新下载链接,文档正文和仓库都不用动,发布节奏完全解耦。
六、工具无关的一段:我自己的选择
需要说明的是,上面这套做法并不绑定某一家服务。自己开对象存储、配好分发,或者用任何一个能提供稳定公开外链、支持多格式输出和多级目录的托管服务,这套流程都能跑通。
我个人图省事,没有单独去维护一套存储,把截图和附件放在了图床小镇,纯粹是用顺手了、省得自己折腾配置;换成具备同样条件的服务,结论完全一样,这只是个人选择,并不是唯一答案。
七、固定下来的流程和上线自检
经过这次调整,我把文档站的素材管理固定成了下面这套流程:
- 写文档前,先把这一篇要用到的截图、附件统一上传,按栏目放进对应目录。
- 配图取 Markdown 链接贴进正文,附件取可直接下载的直链。
- 仓库里只提交 Markdown 正文和必要配置,保持仓库轻量。
- 改版截图用同名覆盖,不新增文件名、不改文档引用。
- 文档站换框架或迁移时,因为图片附件都是完整外链,正文搬过去链接照样有效,不用重新排素材路径。
每次发布前,我还会按这份清单自检:
- 无痕窗口打开,所有配图都能正常加载、没有裂图
- 附件链接点击能正常下载或预览,没有跳转到登录页
- 外链是长期稳定地址,不依赖会过期的临时签名
- 仓库里没有残留大体积二进制文件,提交历史保持干净
- 手机和电脑分别打开一次,确认多端显示正常
整套调整做完,最直观的变化是文档仓库重新瘦了下来,clone 和 CI 都快了不少;而帮助中心该有的图、该下载的附件,读者那边一个都没少。
如果你也在一个人维护产品文档或帮助中心,不妨先把「内容」和「素材」分开看,思路会清晰很多。
官网:imgbed.cn