很多团队第一次备份语雀时，会把「导出任务完成」等同于「知识库已经可长期保存」。真正交接、迁移或离线打开时才发现：Markdown 正文还在，图片变成远程链接；附件文件夹为空；表格只剩一张截图；画板在目标工具里无法预览。这类问题不一定是导出工具坏了，更多时候是资源类型、权限、路径和验收方式没有分开处理。
这篇文章聚焦排障和恢复。基础批量导出流程可以先看 语雀知识库批量导出完整教程；如果你只遇到少量失败文件，可以配合 单文件重新下载功能 精确补导；图片长期保存的细节，可参考 语雀图片本地化备份清单。
- 先定位缺失类型，再决定重试方式：图片、附件、表格、画板的判断标准不同。
- 不要只看导出成功率：离线打开、文件大小、相对路径和随机抽样同样重要。
- YuqueOut 的价值是本地补齐和验收：导出、转换、图片本地化和重试都在浏览器本地完成。
- 保留只读原始归档：补导、改名、清洗都在副本里做，方便回滚。
为什么导出完成仍可能缺资源？
语雀知识库不是单一文本文件。一个页面里可能同时包含正文、远程图片、附件下载地址、表格数据、画板、嵌入文件、加密内容和跨空间引用。导出工具需要逐项读取、转换、下载、改写路径并保存到本地目录。任何一个环节被权限、网络、浏览器下载策略或文档类型限制打断，最终目录都可能看起来「有文章」，但缺少关键资源。
常见误判有三种。第一，Markdown 能打开，但图片仍指向语雀远程地址，离线或迁移到 Git 后就裂图。第二，附件链接仍在正文里，但附件文件没有落到本地目录，交接时无法下载。第三，表格和画板被当成普通文档验收，只检查了标题和正文，没检查数据格式、图片导出和长期预览。
先做 5 分钟基础检查
遇到缺失，不建议立刻全部重导。先把问题缩小到一类资源、一批文件或一个知识库目录。
| 检查项 | 判断方式 | 下一步 |
|---|---|---|
| 文件明细 | 查看失败、跳过、未完成的单文件记录 | 优先单文件重试 |
| 离线打开 | 断网后打开 Markdown 或 HTML 预览 | 定位远程链接依赖 |
| 资源目录 | 检查 assets、images、attachments 是否为空或大量 0 字节 | 重做图片或附件本地化 |
| 特殊类型 | 抽查表格、画板、加密文档、收藏夹 | 改用专用格式导出 |
这个检查能快速回答一个关键问题：是「某几个文件失败」，还是「整个导出策略不适合这个知识库」。前者用补导更快；后者应该先改设置，例如开启图片本地化、调整表格格式、把画板导出为 PNG/SVG，再重新跑对应目录。
图片缺失怎么定位
图片问题最常见，也最容易被误判。先打开导出的 Markdown，搜索 http、cdn、yuque 或图片语法 ![]。如果图片地址仍是远程 URL，说明当前包还依赖语雀线上资源，不适合作为长期备份或迁移源。此时应重新用 YuqueOut 开启图片本地化导出，让图片文件落到本地目录，并把正文路径改写为相对路径。
如果正文已经是相对路径，但预览仍裂图，检查三个点：路径大小写是否被系统或同步工具改写；图片文件是否实际存在；图片文件大小是否为 0。团队经常把 Markdown 文件单独复制给别人，却漏掉同级 assets 目录，这不是转换失败，而是交付包不完整。正确做法是把 Markdown、图片目录、附件目录作为一个整体移动。
图片来源如果需要登录态，也可能在导出过程中间歇失败。长时间导出大知识库时，建议保持语雀页面登录状态有效，避免浏览器休眠，并在导出后通过随机抽样检查重要页面。更完整的图片路径和离线验收方法，可以看 语雀图片防盗链与本地化处理。
附件缺失怎么补导
附件比图片更容易受权限和登录态影响。有些附件在正文里只是一个链接，真正下载时还需要当前账号拥有访问权限；有些附件来自协作文档或团队空间，管理员调整权限后，正文可读不代表附件还能下载。排查时不要只看文档是否导出成功，要在文件明细里确认附件请求是否成功。
补导附件时，先回到原语雀页面确认附件仍然存在、当前账号能打开，然后在 YuqueOut 中对对应文档单文件重试。如果只有附件失败而正文成功，优先补导单文件，不要把整个知识库重跑一遍。若附件文件名包含特殊字符，下载后还要检查本地文件名是否被浏览器或操作系统改写，避免正文链接和实际文件名不一致。
用于交接的附件目录建议额外保留一份清单：原文档路径、附件名、本地路径、文件大小、抽查结果、负责人。这样后续迁移到内部知识门户、Git 仓库或压缩包归档时，可以快速发现「正文在、附件不在」的问题。
表格和画板怎么验收
表格和画板不能只按普通 Markdown 验收。表格要看下游用途：写文档、放 Obsidian 或静态站点时，Markdown 表格便于阅读和搜索；做数据处理时，CSV 更适合；要保留多工作表、格式、合并单元格或原始审计痕迹时，Excel 更稳；需要网页预览时，HTML 更直观。详细格式选择可参考 语雀表格导出验收清单。
画板、白板、流程图和思维导图更不适合强行转纯文本。迁移时应导出 PNG 或 SVG，把图片放在本地资源目录，再在 Markdown 中补充图名、用途、关键节点、维护人和更新时间。这样既能让人看图，也能让搜索或 AI 知识库读到文字摘要。具体做法可参考 语雀画板导出迁移清单。
如果你发现「文档数量对得上，但关键表格或画板缺了」，不要只检查导出总数。按文档类型抽样：普通文档、表格、画板、加密文档、收藏内容至少各抽 3-5 个。大知识库交接时，这比单纯看成功率更可靠。
什么时候用单文件重试
单文件重试适合三类场景：少量网络超时、少量权限刷新后可访问、少量特殊文档需要改格式后补导。比如 800 篇文档里只有 6 个失败项，先在 YuqueOut 设置页的文件明细里筛出失败文件，再逐个点「重新下载」。这样不会浪费时间处理已经成功的文件，也能保留原始导出记录。
不适合单文件重试的情况也要明确：如果整批图片都没有本地化，说明设置或导出策略有问题；如果全部附件都为空，可能是登录态、浏览器下载权限或保存目录策略问题；如果所有画板都缺失，应检查画板格式选择，而不是逐个重试。判断标准是：问题集中在少数文件，用重试；问题覆盖同一类资源，用设置修正后按目录重导。
交付前完整性清单
真正可交付的语雀导出包，应该经得起离线、迁移、交接和回滚。建议每次归档前保留两份目录：一份只读原始导出，一份用于改名、脱敏、补摘要和删除过期内容的工作副本。这样补导失败时还能回到原始状态，不会越修越乱。
- 断网打开 10-20 篇关键文档，图片不依赖远程语雀地址。
- 检查资源目录不为空，图片和附件没有大量 0 字节文件。
- 抽查表格的中文、日期、金额、链接、合并单元格和多工作表。
- 抽查画板 PNG/SVG 是否能预览，并有文字摘要说明用途。
- 对失败文件执行单文件重试，并记录无法恢复的原因。
- 把 Markdown、assets、attachments、表格和画板作为整体压缩或提交。
- 给交接包写 README：导出日期、Yuque 空间、负责人、排除内容、验收人。
YuqueOut 的角色不是替你决定哪些资料该公开、该迁移或该上传到其他平台，而是把语雀里的资料尽可能完整地导出到本地，让你能在本机完成检查、补导、脱敏和归档。这个边界很重要：工具负责本地导出和恢复，团队负责验收标准和后续分发。
常见问题
Q: 导出目录里文件数和语雀文档数对不上，一定有丢失吗？
不一定。目录层级、附件、图片、表格多格式、画板图片都会影响文件数。更可靠的方式是按语雀目录抽样核对标题和关键资源，再看 YuqueOut 文件明细中的失败项。
Q: 我已经有一篇旧的导出失败指南，还需要这份清单吗？
旧指南更适合定位网络、权限、登录态和格式报错；这份清单聚焦导出完成后的资源完整性验收，尤其是图片、附件、表格和画板是否能离线保存、迁移和交接。
Q: 可以把补导后的文件直接覆盖原归档吗？
不建议。先把补导文件放进工作副本，确认路径、文件名和预览都正确，再决定是否替换原目录。团队交接时保留原始归档更容易追溯。