• 桌面应用
• CLI
• 数据工程

万能导 Wandao 是一款多平台知识库 Markdown 导入导出工具，支持微信公众号导出、语雀导出导入、飞书导出导入、知识星球、印象笔记、有道云笔记、OneNote、ima 等平台，迁移全程尽量保留目录结构、图片和原始格式。批量执行导出/导入任务时，最容易碰到的三类问题是：登录失效、图片缺失、进度卡住。本文按问题类型整理成速查清单，对照症状即可找到对应处理方式，无需翻查源码。

第一次使用？建议先看 docs/使用教程.md，熟悉"选平台 → 登录 → 读取目录 → 执行任务"的基本流程。

速查总览：先看症状，再定位原因

桌面端的错误提示都来自统一的错误规则表（wandao_core/errors.py#L27-L106），会自动把原始报错翻译成通俗中文。按下表对照即可：

问题一：登录失效如何处理（重新登录保存凭证方法）

如何识别"登录失效"

出现以下任一情况，基本都是浏览器登录态（Cookie）过期了：

• 用户日志提示"登录状态可能失效"，或包含"未登录""登录失效""401"等字样
• 弹出的浏览器页面被平台打回登录页
• 之前正常的知识库链接突然打不开

万能导凭证文件只保存 Cookie、不保存账号密码，且仅存在本机（见 本地数据存储策略）。Cookie 有效期由各平台决定，重新登录属于正常操作，不用担心弄坏配置。

重新登录并保存凭证（3 步）

1. 在平台导出/导入页面，填写入口 URL（知识库或文档链接）
2. 点击**"登录并保存凭证"**，在弹出的浏览器中手动完成登录
3. 确认浏览器中能正常打开目标页面后，回到万能导点击**"我已完成登录，保存凭证"**

💡 关键动作：先在浏览器里确认目标页面能打开，再回工具点确认。这一步能避免绝大多数"明明登录了还是报错"的情况。

几个容易踩的坑：

• 印象笔记比较特殊：不需要入口 URL，填写账号密码后点击"登录并同步"即可，不保存明文密码
• 平台侧改过密码或清过浏览器 Cookie后，必须重新保存一次凭证
• 飞书在 v1.3.5 起对过期登录态只恢复凭证并重试一次，避免重复导航死循环，详见 docs/releases/v1.3.5.md

浏览器找不到或打不开

日志提示"没有成功连接到可控制的浏览器"或 DevTools 相关错误时：

1. 进入设置 → 自动化浏览器，默认"自动检测（推荐）"通常足够
2. 检测不到时点击"重新检测"，或"手动选择浏览器"指定可执行文件
3. 浏览器装在非常规路径时，可设置WANDAO_BROWSER环境变量为浏览器完整路径（见 使用教程）

问题二：导出图片缺失怎么办（失败资源重试方法）

先判断：正文导出来了吗？

第一判断标准是正文 Markdown 是否已生成：

• ✅ 正文在、只是图没显示 → 提示为"图片或附件处理失败"，只需重试资源
• ❌ 整篇文档都没导出 → 在任务中心点"打开报告"看具体失败文件

万能导把资源失败与文档失败严格分开（见 task_report.js），"重试失败项"不会把几百张图片当作文档重跑，也不会反过来。

语雀导出图片缺失

• 语雀导出默认本地化正文图片并尝试下载附件；公开密码库、私有知识库的附件需要登录态——先点"登录并保存凭证"，确认浏览器能访问该知识库，再导出
• 附件特别大时，可在"导出选项"里取消"同时下载附件"，避免单个大文件卡住整个任务

语雀导入图片不显示

导入前建议先"生成计划"，工具会在 Markdown 目录生成00-语雀导入计划.json，直接列出关键数据：

• localImageCount：能找到并准备上传的本地图片数
• missingLocalResourceCount：Markdown 引用了但本地找不到的资源数

对照 语雀 Markdown 导入排查指南 处理：

• 本地图片缺失：把图片文件放回 Markdown 引用的路径，重新生成计划
• 远程图片不显示：确认该图片链接可免登录公开访问
• 上传超时：调大"图片上传超时秒"和"失败重试次数"
• 单篇图片很多："资源上传并发"保持 2、最多 3；遇到限流或网络不稳再降回 1

飞书导入图片不显示

先确认本地 Markdown 引用的图片路径真实存在（最常见原因），再勾选"修复本地图片"后重试。若源 Markdown 引用了飞书未随节点提供的相对.assets资源，正文会正常导出，缺失资源会作为"部分完成"明确写入报告，不会静默假装成功。

一键重试失败资源

进入任务中心找到对应任务，点击**"重试失败项（N）"**，只补跑失败的资源，不用整轮重来；还可以"导出失败日志"留存证据、"提交错误报告给开发者"。

问题三：导出进度卡住怎么办（中断后如何恢复）

进度短时不动，先看日志

进度短时间不动，通常是在等待页面渲染、图片下载、请求延迟或平台响应，不一定是卡死了：

1. 看页面底部用户日志：只显示普通用户能直接理解的内容；点"详细日志"可切换到含完整输出的调试日志
2. 日志提示"网络请求超时" → 检查网络/代理，等待后重试
3. 日志提示"请求过于频繁，平台暂时限流" → 等待一段时间，调大请求延迟再继续。默认是每次请求前等待0.8 + 0~0.4秒，不建议调成 0

任务中断后如何续跑

点击"停止当前任务"时，工具会在当前文档或图片处理完成后的安全点停止，并保留已导出的文件和报告：

• 继续/重试：任务中心点击"继续"会优先使用平台声明的失败重试能力；暂不支持的平台按历史命令重新执行，适合增量补齐
• 增量导出：勾选"增量导出"后，工具识别本地 Markdown 底部的来源标记，已导出的文档自动跳过，只补缺失内容
• 编号不漂移：知识星球等中断续跑会从输出目录现有最大编号继续，不重复生成文件（见 v1.3.5 发布说明）

每个任务的进度都记录在本地checkpoint.sqlite中（见 本地数据存储策略），即使程序异常退出，重新打开后也能从断点精确恢复。

重试失败项：只补跑失败的部分

任务中心每条记录都带状态标签和统计（总数、导出、跳过、失败、正文成功、图片成功）：

• 已完成→ 收工
• 部分完成→ 点"重试失败项（N）"只补跑失败项
• 每条记录还提供"复制报告""打开报告""打开输出""导出失败日志"，方便保存证据

问题四：权限不足或无访问权限怎么处理

日志提示"当前账号或应用没有访问权限"（403）或"目标内容不存在或当前账号不可见"（404）时：

• 先用同一账号在浏览器打开链接验证：浏览器也打不开，就不是万能导的问题
• 团队知识库需要确认账号是否有对应文档/知识库的读权限，必要时请所有者授权
• 万能导不会破解登录或绕过平台权限，只处理你有权访问的内容，详见 合规说明

飞书导入还有两个典型错误码：

排查完毕仍无解？按这份清单整理反馈

1. 点日志栏的**"提交错误报告给开发者"——工具会自动复制一份已脱敏**的详细报告（Cookie、Token 等敏感信息已被屏蔽）
2. 在任务中心点"复制报告"/"打开报告"，拿到任务统计与失败项明细
3. 反馈时附上：平台与操作类型（导出/导入）、错误提示原文、详细日志关键片段

⚠️ 请勿在截图或日志中公开 Cookie、账号密码、Token、API Key 等敏感信息，参见 安全策略。

相关资料

• docs/使用教程.md：完整操作说明，含请求延迟、停止任务与输出目录
• docs/tutorials/yuque-import-troubleshooting.md：语雀导入计划、图片与失败项排查
• docs/tutorials/wandao-usage-tutorial.md：导入导出流程图文教程
• docs/releases/v1.3.5.md：登录会话修复与中断续跑细节

• 桌面应用
• CLI
• 数据工程