幕布批量导出失败时，不要第一时间重置任务。先看失败范围：如果是全部失败，多半是登录态或下载设置问题；如果只有少量文件失败，通常用「重试失败的文件」即可；如果导出中途被关掉，重新打开插件后先看状态是否恢复。
Mubu Exporter 的设计重点就是长任务可靠性：每个文件有独立状态，导出进度会保存到本地，失败文件可以单独重试，导出间隔也做了节流，尽量避免把几百篇笔记一次性请求得太快。
排查顺序：先确认幕布登录状态 → 关闭 Chrome 下载前询问 → 看插件日志里的失败原因 → 少量失败用重试 → 大量失败暂停后检查网络和账号状态 → 设置页查看文件树和最慢 TOP10。
先判断是哪一种失败
| 现象 | 常见原因 | 优先处理 |
|---|---|---|
| 获取文件信息失败 | 幕布未登录或登录过期 | 重新登录 mubu.com |
| 每个文件都弹保存框 | Chrome 开启了下载前询问 | 关闭下载前询问 |
| 导出到一半停住 | 网络波动、页面关闭、Service Worker 重启 | 重新打开插件查看状态 |
| 少量文件失败 | 单个文档异常或接口短暂失败 | 点击重试失败文件 |
| PDF 批量失败 | 幕布转换接口不可用或登录态失效 | 先测 Word/HTML，再重试 PDF |
| 下载目录很乱 | 没有配置下载子文件夹 | 在设置页配置子目录 |
关键是不要把所有问题都当成「插件坏了」。批量导出涉及幕布登录态、网络、Chrome 下载权限、文件路径、远程转换接口和本地格式转换。按现象拆开排查，速度会快很多。
问题一：未检测到 Jwt-Token
插件需要读取你在 Chrome 里登录幕布后的 Jwt-Token Cookie 来完成鉴权。如果日志提示未检测到 Jwt-Token，说明当前浏览器没有有效登录态。
- 点击插件右上角登录按钮，或直接打开 mubu.com/login。
- 确认能正常进入幕布文档列表。
- 回到插件，重新点击「获取文件信息」。
不需要手动复制 token，也不建议把 token 粘贴到任何地方。当前插件只从浏览器本地 Cookie 读取认证信息。
问题二：导出时一直弹保存窗口
如果每导出一个文件 Chrome 都弹一次保存位置，批量导出会变成手动劳动。原因通常是浏览器开启了「下载前询问每个文件的保存位置」。
处理方法：
- 打开 Chrome 设置。
- 进入「下载内容」。
- 关闭「下载前询问每个文件的保存位置」。
- 回到插件重新开始导出。
插件设置页也提供了「打开下载设置」入口。关闭这个选项后，插件才能自动把文件保存到指定子目录，比如 幕布备份/项目A/会议纪要.md。
问题三：导出中途关闭浏览器怎么办？
Chrome Manifest V3 的后台是 Service Worker，长任务过程中后台有可能被浏览器回收。为了解决这个问题，插件会把任务状态保存到 chrome.storage.local。每个文件都有状态：pending、in_progress、success、failed。
如果导出中途关闭浏览器或插件窗口：
- 重新打开 Chrome 和幕布页面，确认仍然登录。
- 点击插件图标。
- 观察进度、日志和失败列表是否恢复。
- 如果任务没有自动继续，先点击暂停/继续或重新开始，并留意已成功文件不会被直接覆盖。
注意：浏览器下载行为可能会给同名文件自动加序号。为了让备份更清晰，建议每次导出前设置一个带日期的下载子目录。
问题四：只有少量文件失败
少量失败是批量任务里最常见、也最好处理的情况。可能是某篇文档内容过大、接口短暂波动、网络瞬断，或者 PDF 转换接口临时返回异常。
正确处理方式是：
- 不要点击重置。
- 等待当前导出任务结束。
- 查看失败列表。
- 点击「重试失败的文件」。
插件会把失败文件重新标记为待处理，再单独导出。这个方式比重新全量导出更稳，也避免重复生成大量已经成功的文件。
问题五：PDF比Markdown更容易失败
这是正常的技术差异。Markdown、OPML、HTML、Word、JSON 主要在插件本地转换；PDF 则需要调用幕布的转换接口。只要远程接口、登录态或网络其中一环不稳定，PDF 就可能比本地格式更容易失败。
建议的排查顺序：
- 先导出 1-3 篇文档为 HTML 或 Word，确认文档读取正常。
- 再切换为 PDF 测试同一批文档。
- 如果只有 PDF 失败，稍后重试，或先保留 HTML/Word 作为替代归档。
PDF/Word 的具体差异可以看幕布导出 PDF/Word 指南。
如何用性能监控定位问题？
插件设置页有「性能监控」区域，可以查看文件树、导出状态、耗时和最慢 TOP10。它适合处理这几类问题：
- 想知道哪些文件已经成功导出。
- 想筛选所有失败文件。
- 想找出特别慢的大文件。
- 想确认文件实际保存到了哪个相对路径。
如果你导出几百篇笔记，不要只盯着弹窗进度条。完成后打开设置页看文件树，能更快确认有没有遗漏。
减少失败率的导出习惯
- 先小批量测试：第一次使用时，先导出一种格式确认流程正常。
- 保持幕布页面登录：长时间导出前刷新一下 mubu.com。
- 关闭下载前询问：避免每个文件都需要手动确认。
- 使用日期子目录：例如
MubuBackup/2026-07-02，避免文件混在一起。 - 重要资料多格式备份：Markdown 用于迁移，HTML 用于查看，JSON 用于兜底。
- 失败项单独重试：不要为了几篇失败文档重新跑全量任务。
如果你的目标是建立长期备份机制，可以把这个流程固定为每月一次。具体策略见幕布每月备份方案。
常见问题
暂停后可以换导出格式继续吗？
不建议。暂停/继续适合恢复同一个导出任务。如果要换格式，建议等当前任务结束，设置新的下载子目录，再重新选择格式导出。这样目录和文件状态更清楚。
重试失败文件会覆盖已导出的文件吗？
不会主动覆盖成功文件。插件会只处理失败项，Chrome 下载 API 对同名文件也会使用自动改名策略，避免直接覆盖。
导出很慢是不是异常？
不一定。插件会在文件之间加入短暂随机间隔，避免请求过快触发限制。文档越多、图片越多、PDF 越多，总耗时越长。真正需要关注的是失败率，而不是单纯速度。
相关链接：