批量导出 500 篇文档，其中 3 篇因为网络超时失败了。之前的做法是：点击「重试失败的文件」，这会重新鉴权并启动一个新的导出流程。虽然只处理失败文件，但整个流程比较重。如果只是想补一两个文件，有点杀鸡用牛刀。
- 设置页「文件明细」中每个文件可独立重新下载
- 保存路径与首次导出完全一致，不会产生重复文件
- 使用当前设置中的格式和引擎配置
- 适合修复少量失败文件，无需重跑整个任务
之前的痛点
在 v1.2 之前，处理失败文件有两种方式：
| 方式 | 操作 | 问题 |
|---|---|---|
| 重试失败文件 | Popup 点击「重试」按钮 | 启动完整流程，对单个文件过重 |
| 重新导出全部 | 重置后重新开始 | 成功的文件也会被重新处理 |
两种方式对于「只想补一两个文件」的场景都不理想。特别是在大批量导出后（比如 1000+ 文档），为了 2-3 个失败文件去走完整流程，等待时间不成比例。
现在的方案
v1.2 在设置页的「性能监控 → 文件明细」中，为每个文件新增了「重新下载」按钮。无论文件状态是成功、失败还是未完成，都可以点击重新导出。
按钮状态变化：
- 重新下载 → 点击前，可操作状态
- 下载中... → 执行中，按钮禁用
- 已完成 → 成功，3秒后恢复
- 失败 → 出错，hover 可查看原因，3秒后恢复
操作步骤
- 打开 YuqueOut 设置页（右键扩展图标 → 选项）
- 点击左侧导航「性能监控」
- 下滑到「文件明细」区域
- 用状态筛选按钮过滤出「失败」的文件
- 在目标文件行末尾点击「重新下载」
- 等待按钮变为「已完成」即可
在「目录结构视图」中同样提供了重新下载按钮，方便在目录结构中定位文件后直接重试。
技术细节
单文件重新下载执行的是完整的导出流程，与批量导出时的逻辑完全一致：
- 读取当前设置中的格式配置（文档/表格/画板各自的格式）
- 根据文档类型和权限自动选择转换引擎（本地/API）
- Markdown 导出时执行图片本地化
- 保存路径按知识库/目录/文件名生成，与首次导出一致
- 如果目标路径已存在同名文件，Chrome 会自动加 (1) 后缀（uniquify 策略）
常见失败原因及处理
网络超时
最常见的失败原因。通常直接点「重新下载」即可成功。如果反复超时，可能是语雀 API 限流，建议等待几分钟后再试。
权限不足（403）
文档的导出权限被管理员限制了。如果文档类型是普通文档（Doc），重新下载时 YuqueOut 会自动尝试本地引擎兜底。如果是 Word/PDF 格式则确实需要权限，可以先切换设置中的格式为 Markdown 后重试。
文档已删除（404）
文档在导出期间被删除或移动了。这种情况重试也会失败，属于正常情况。
登录态过期
长时间未操作后 Cookie 过期。解决办法：在浏览器中重新访问一次 yuque.com（自动刷新 Cookie），然后重试。
常见问题
Q: 重新下载会覆盖已有文件吗？
不会直接覆盖。Chrome 下载 API 使用 uniquify 策略：如果路径已存在同名文件，会自动加数字后缀（如 文档 (1).md）。如果你想替换旧文件，需要手动删除后再重新下载。
Q: 可以批量重试所有失败文件吗？
可以。Popup 中的「重试失败的文件」按钮仍然保留，适合一次性重跑所有失败文件。单文件重试是针对精确补充的场景。
Q: 重新下载的格式和首次导出不一样怎么办？
重新下载使用当前设置中的格式配置。如果你在导出后修改了格式设置（比如从 md 改为 docx），重新下载会按新设置执行。如果需要保持一致，确保设置未变再点击重试。