语雀图片本地化备份：Markdown 导出、相对路径和长期可读检查清单

很多语雀备份失败，不是因为正文没有导出，而是图片仍然停留在远程链接里。Markdown 文件看起来很完整，真正打开到本地编辑器、静态博客、Git 仓库或 AI 知识库时，截图、流程图、表格截图和产品界面却全部失效。对长期归档来说，这类备份只能算半份备份。

YuqueOut 的定位是先把语雀资料安全拿到本地：正文转换为通用格式，图片保存为本地文件，路径改成可迁移的相对引用。后续你可以把这份资料放进 Obsidian、Git、静态博客、Dify、OpenAI File Search 或内部 RAG 系统，但上传到哪个平台、公开哪些内容，都由你自己决定。

为什么图片本地化是备份关键

知识库里的图片通常不是装饰。它们可能是操作截图、产品界面、架构图、流程图、报错截图、表格截图或会议白板。如果只保存 Markdown 正文，很多教程和排障文档会丢失关键上下文。

图片外链还有三个长期风险：

• 访问环境变化。离开语雀网页后，本地编辑器、博客域名和 AI 平台不一定能继续访问原图片地址。
• 权限上下文变化。团队成员离职、知识库权限调整、文档转移后，原链接可能不再对当前账号可见。
• 归档不可验证。只要图片还依赖线上服务，你就无法证明这份备份在断网、迁移或多年后仍然完整。

因此，长期备份的基本标准应该是：断开语雀环境后，打开本地文件仍能读完正文、看到图片、追踪附件，并保持目录结构可理解。

推荐导出设置

如果目标是长期备份和迁移，推荐从以下设置开始：

1. 格式选择 Markdown。Markdown 适合 Git diff、全文搜索、静态站点生成和 AI 知识库分段。
2. 开启图片本地化。让图片下载到本地 assets 目录，并把正文图片链接替换为相对路径。
3. 保留知识库目录。不要一开始就拍平所有文件；目录是后续排查来源、拆分权限和批量迁移的依据。
4. 特殊内容单独抽查。包含画板、表格、加密文档、协作文档和收藏夹的知识库，要在导出后单独验收。
5. 大知识库分批执行。先导出一个目录或 20 篇代表性文档，确认路径和图片策略正确，再跑全量。

如果你还没确定源格式，可以先看 语雀文档批量转 Markdown 完整指南。如果遇到导出失败或下载中断，再配合 语雀导出失败排查指南定位是网络、权限、格式还是单文件问题。

本地目录应该长什么样

一份可迁移的导出包，应该让人一眼看懂正文和资源的关系。常见结构可以是：

yuque-backup/
├── 产品手册/
│   ├── 安装指南.md
│   └── assets/
│       ├── install-step-01.png
│       └── install-step-02.png
├── 故障排查/
│   ├── 图片裂图怎么办.md
│   └── assets/
│       └── broken-image-example.png
└── export-report.html

不同工具的目录命名可能略有差异，关键不是固定叫 assets，而是满足三点：图片文件真实存在，Markdown 中引用的是相对路径，整个目录移动到别的位置后仍能打开。

如果要进入静态博客，可以再把图片移动到站点的 images/、public/ 或文章资源目录。但这个动作应该发生在“已确认本地导出完整”之后，不要一边导出一边改路径，否则出错时很难判断问题来自语雀、导出工具还是站点构建。

导出后的验收清单

导出完成并不等于备份完成。建议至少做一次轻量验收：

团队场景建议把验收记录放在导出包旁边，例如记录导出日期、账号、知识库范围、跳过文件、失败文件和重试结果。这样下一次增量备份时，不需要重新猜测上次到底漏了什么。

迁移到博客、Obsidian 和 AI 知识库

图片本地化之后，不同目标平台的处理重点不同：

• Obsidian。保持 Markdown 和图片相对路径，先打开 Vault 抽查链接，再决定是否启用统一附件目录。
• 静态博客。先确认本地图片完整，再按站点规范改为公开图片路径，补 canonical、OG 图片、sitemap 和 FAQ。
• AI 知识库。即使目标平台主要检索文本，也要保留图片目录，方便人工核对答案来源和后续多模态扩展。
• Git 归档。如果图片很多，注意仓库体积；可以把原始导出包和公开博客源码分开管理。

如果你的目标是公开站点，可以继续看 语雀迁移到静态博客；如果目标是 RAG 或企业知识库，可以参考 语雀内容如何整理成 AI 知识库。这几条路线的共同前提，都是先拿到完整、可移动、可复核的本地资料包。

企业资料的安全边界

图片本地化会让资料更容易迁移，也意味着更需要管好边界。导出前先确认哪些知识库可以进入个人电脑，哪些必须放在公司受控目录，哪些不能上传到公开博客或第三方 AI 平台。

建议企业按三类处理：

• 公开内容。产品教程、帮助中心、公开 FAQ，可以进入博客和搜索入口。
• 内部内容。SOP、项目复盘、客服升级流程，只进入内部知识库或受限 AI 应用。
• 敏感内容。客户资料、合同、价格、人事、财务和未发布方案，默认不进入 AI 平台和公开站点。

YuqueOut 负责本地导出和转换，不替你判断哪些内容应该公开。团队负责人需要在导出后做一次资料分级，必要时参考 企业语雀导入 AI 知识库前的权限治理。

常见错误和修复方式

错误一：只保存 Markdown，不保存图片目录

这会让备份在本机以外的环境失效。修复方式是重新导出并开启图片本地化；如果已经有 Markdown，可以先检索 http 图片链接，确认哪些资源仍在远端。

错误二：把图片移动后没有改路径

静态博客经常需要把图片放到统一目录。移动前先保留一份原始导出包，移动后用本地预览或构建检查所有图片引用。

错误三：把内部截图发布到公开博客

很多截图包含账号、客户名、内部系统地址或价格信息。公开前要逐张检查，必要时打码、重画示意图，或者直接删除。

常见问题

语雀导出时为什么要开启图片本地化？

因为长期备份、静态博客迁移、Obsidian 管理和 AI 知识库导入都不应依赖原语雀图片外链。图片本地化会把图片文件保存到本地目录，并把 Markdown 中的图片链接改成相对路径。

只导出 Markdown 不下载图片可以吗？

只适合临时阅读，不适合长期备份。外链图片可能受登录态、权限、Referer、链接有效期或服务变更影响，迁移到本地编辑器、静态博客或 AI 平台后容易裂图。

图片本地化后应该如何检查？

至少抽查 Markdown 预览、assets 目录、相对路径、文件名冲突、空文件、封面图和目标平台导入效果。大型知识库应先抽样 20 篇，再批量处理。

本地图片会被 YuqueOut 上传到服务器吗？

不会。YuqueOut 的导出和转换在浏览器本地完成，不把文档内容或图片上传到第三方服务器。导出后的文件是否上传到其他平台由用户自行决定。

AI 知识库需要图片本地化吗？

需要。即使目标 AI 平台主要检索文本，本地图片仍能保留截图、流程图、表格截图和产品界面上下文，便于人工复核、后续重建页面和补充多模态材料。