文档生成拖慢ci/cd流水线的主因是调用方式、依赖加载和输出处理逻辑不当，而非工具本身；常见表现为npm run docs或sphinx-build阶段耗时激增、启动开销大、输入扫描失控、模板同步阻塞、输出路径未清理及参数配置不合理。
HTML文档生成工具本身不是性能瓶颈，真正拖慢CI/CD流水线的是它的调用方式、依赖加载和输出处理逻辑。
为什么文档生成会拖慢流水线？
常见现象是：流水线卡在 npm run docs 或 sphinx-build 阶段，耗时从几秒涨到2分钟以上，且每次构建波动极大。
- 工具启动开销被低估：比如
jsdoc启动时需加载整个Node.js运行时 + AST解析器，冷启动比热构建慢3–5倍 - 输入扫描范围失控：未配置
exclude或include，导致扫描 node_modules 或测试目录，I/O时间翻倍 - 模板渲染阻塞主线程：
swag init默认使用同步FS读取所有Go文件，遇到大项目直接触发V8堆内存警戒线（>1.4GB） - 输出路径未清理：重复生成时，
docs/目录残留旧文件，rsync或gh-pages插件做全量diff，CPU占用飙升
Swag、JSDoc、Sphinx 的关键参数差异
不同工具对CI友好的程度差异极大，不能统一配置。
-
swag init -g main.go -o ./docs/swagger.json --parseDependency --parseInternal：开启--parseDependency会让它递归解析所有import包，CI中应禁用；--parseInternal在私有模块场景下才需要，公开仓库可关 -
jsdoc -c jsdoc.json -r src/ --no-cache：必须加--no-cache，否则JSDoc会在~/.jsdoc/写缓存，CI环境无家目录易失败；-r若不加范围限制，会扫整个工作区 -
sphinx-build -b html -j 2 source build：-j 2是安全上限，设为-j 4可能因内存不足被OOM Killer干掉；source/conf.py中若启用extensions = ['sphinx.ext.viewcode']，会触发额外源码高亮解析，CI中建议关闭
如何让文档生成不成为流水线短板？
核心思路是：隔离、裁剪、复用。
- 把文档生成拆成两个job：一个只做元数据提取（如
swag init -o swagger.json），另一个只做静态站点渲染（mkdocs build），失败时可单独重试 - 用
git diff --name-only HEAD^ HEAD | grep '\.ts$\|\.go$'判断是否真有必要生成——只有接口文件变更才触发完整流程 - 缓存
node_modules和_build/doctrees目录，但别缓存最终docs/输出，它该由部署阶段清空重建 - 在GitHub Actions中，避免用
actions/checkout@v4默认的fetch-depth: 1，否则git diff拿不到上一次提交，误判为“全量变更”
最容易被忽略的一点：文档生成工具的 exit code 不一定代表成功。比如 jsdoc 遇到语法错误会返回非零码，但某些CI模板里用 || true 忽略了它，结果静默产出空文档站——得检查生成后的 docs/index.html 是否真实存在且包含 <title></title> 标签。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
