如何把本手册导入 Apifox（含图片处理说明）

本手册以「多个 Markdown 文件 + 一个 images 图片目录」的形式交付，可直接导入 Apifox 文档站。本篇说明导入步骤与注意事项。

给维护者看的，不是给最终客户看的。导入完成后可在 Apifox 里隐藏或删除本篇。

一、产物结构

docs-manual/
├── 00-入门指南/            (.md ×6)
├── 10-运营管理端/          (.md ×25)
├── 20-客户自助端/          (.md ×5)
├── 30-单机服务器端/        (.md ×1)
├── 90-附录/                本篇 + FAQ + 截图待补清单
└── images/                 全部界面截图（被各 .md 以 images/xxx.png 引用）

文件名统一带 00- 10- 20- 数字前缀：即使导入后目录层级被打平，也能靠前缀保持顺序与归类。

每个 .md 内的一级标题（#）就是它在 Apifox 文档树里的名称。

二、导入步骤（Apifox）

打开目标项目 → 左下角 项目设置（或顶部「更多 → 导入数据」）。

选择 导入数据 → Markdown。

选中 docs-manual/ 下需要导入的 .md 文件（可多选批量导入）。

确认导入。每个 .md 会成为一个独立的 Markdown 文档节点。

关于目录树：Apifox 的 Markdown 批量导入是「每个文件一个文档」。若导入后所有文档堆在同一层，可在 Apifox 文档树里手动新建目录（入门指南 / 运营管理端 / 客户自助端 / 单机服务器端 / 附录），再把对应文档拖进去——靠文件名前缀很好辨认。也可以按文件夹分批导入，导入前先在 Apifox 建好对应目录。

三、图片如何显示（重要）

Markdown 里的图片是用相对路径 images/xxx.png 引用的。Apifox 的 Markdown 文本导入不会自动把本地图片一起上传，因此直接导入后图片可能不显示。三选一处理：

方案 A（推荐，最稳）：导入文本后，在 Apifox 文档编辑器里逐篇把对应截图拖入/粘贴到图片位置，Apifox 会自动上传并生成它自己的图床链接。images/ 目录就是你要拖入的素材库，文件名和文档里的引用一一对应。

方案 B：把 images/ 目录整体上传到你们的静态资源服务器/对象存储/图床，得到一个基础 URL（如 https://cdn.example.com/dcim/），然后把所有 .md 里的 images/ 批量替换成该 URL。替换后再导入，图片即可直接显示。

方案 C：导入纯文本，图片暂不处理。文档里凡未配图处已是「📷 截图待补充」提示，不影响阅读。

四、补充 / 更新截图的流程

仍有部分界面（各类弹窗/表单、详情子标签、客户端与单机端页面）标注为「截图待补充」，清单见《截图待补充清单》。补全方法：

截好对应界面，命名后放进 docs-manual/images/（例如 servers-rebuild-form.png）。

在对应文档里，把该处的提示整行

替换为图片引用：

重新导入更新后的 .md 到 Apifox（或在 Apifox 里手动更新对应文档、把图片拖进编辑器）。

说明：首次成稿时用的是  占位 + manual-tools/apply_screenshots.py 批量回填脚本；该脚本会"消费"占位注释，因此后续增补改用上面的手动替换即可（脚本仍保留备用）。

五、维护建议

系统界面/功能更新后，对应章节的文字与截图需同步更新；改动较大的模块，建议重读对应源码后修订。

images/ 里的文件名即「内容指纹」，请勿随意改名，否则需同步改 .md 引用。

本手册内部用「见《某某章节》」相互引用；在 Apifox 中可改成文档内链以增强跳转体验。

如何把本手册导入 Apifox（含图片处理说明）

一、产物结构#

二、导入步骤（Apifox）#

三、图片如何显示（重要）#

四、补充 / 更新截图的流程#

五、维护建议#

一、产物结构

二、导入步骤（Apifox）

三、图片如何显示（重要）

四、补充 / 更新截图的流程

五、维护建议