扩展装好以后，不要马上把整个知识库丢进批量队列。先用一篇不含敏感信息的测试文档走完一次导出，你会更快知道安装、权限和图片处理有没有问题。
这篇测试不需要复杂文档。有一级、二级标题，几段正文，一张图片和一个表格就够了。
先确认扩展真的在当前页面工作
打开浏览器里的飞书文档，不要用桌面客户端。点击工具栏上的飞书工具箱图标，看看侧栏能不能读到当前页面标题和正文。
如果图标没有反应，先在扩展管理页点一次“重新加载”。仍然没反应时，再检查是不是装到了另一个浏览器，或者当前页面还在飞书登录页。
扩展能读页面，说明安装和页面注入这条链路通了。接下来再看导出。
第一篇测试文档怎么选
不要拿客户合同、报价单或内部架构图做第一次测试。选一篇自己写的普通笔记，标题和正文都简单，最好带一张能公开的图片。
导出前先记住三件事：
- 正文里有没有表格或代码块。
- 图片在正文中的顺序。
- 文档能不能在你的账号下正常打开和下载。
这三项会决定后面检查什么。
用免费的 Markdown 导出跑一次
在扩展面板里选择“导出 Markdown”。第一次可以先不打开图片 ZIP、PDF 或批量导出，把免费路径单独跑通。
保存文件后，先做四个检查：
- 标题层级是否和原文一致。
- 表格是否还保持行列关系。
- 代码块和引用有没有丢格式。
- 图片位置是否还在原文附近。
如果只是文本和基础结构有问题，回到扩展面板里的“清洗诊断”，查看哪些块被保留、哪些块被删掉。诊断结果比反复重装扩展更有用。
再决定要不要处理图片
飞书文档里的图片可能有三种状态：已经保存到本地、仍指向在线地址、因为权限无法读取。
把 Markdown 和图片目录一起移到新文件夹，再断网打开。如果图片还在，导出结果是可移植的；如果图片消失，就把这篇文档加入 Markdown + 图片 ZIP 的测试范围。
图片 ZIP 属于 Pro，每项付费功能可以先免费试用 3 次。先用一篇测试文档判断是否真的需要，比直接购买更稳妥。
再试一次批量导出
单篇没有问题后，再选两到三篇同目录文档加入队列。不要先看数量，先看四件事：
- 文件夹层级是否还原。
- 每篇文档是否都生成了 Markdown。
- 图片是否跟着对应文档走。
- 失败任务有没有明确提示。
测试通过后，再处理几十篇或几百篇的正式资料。
遇到问题先看哪里
| 现象 | 先检查 |
|---|---|
| 点图标没反应 | 是否在飞书网页版，扩展是否已启用 |
| 正文少了一段 | 清洗诊断里的删除样本 |
| 表格错位 | 原文是否使用了复杂合并单元格 |
| 图片裂图 | 图片是否仍然是飞书在线地址 |
| 批量任务失败 | 是否还能打开该文档，是否有下载权限 |
先定位问题落在哪一层，再决定要不要换方法。多数情况下，只是某一种内容没有走到预期分支，没必要整包重做。
什么时候不该继续用扩展
需要定时运行、无人值守上传或接入现有自动化系统时，浏览器扩展不适合承担长期后台任务。此时的检查文档仍然有用，但导出方式应该换成开放平台 API 或命令行工具。
第一次导出不求一次搬完。用一篇文档把权限、正文、图片和文件夹路径都看一遍，后面处理真实资料时就不会一边导一边猜。