把 5000+ 条为知笔记迁移到有道云笔记：一次踩坑、回滚与修复实录

迁移实录

5009 条为知笔记、44499 个图片资源：从 Markdown 导出、75% 图片压缩，到使用官方 YoudaoNote CLI 导入、回滚错误数据和最终云端对账。

5009 条笔记 · 44499 个资源 · 支持断点续传

原始数据有什么

扫描为知笔记本地数据后，得到的核心数字如下：

迁移目标有两个：一是生成结构清晰、可长期保存的 Markdown；二是在有道云笔记中新建“为知笔记”根目录，保留原目录作为二级目录。

最初的导入方案直接操作有道客户端的本地数据，并把 Markdown 正文写入笔记。结果图片语法被当作普通文本显示：

![](https://note.youdao.com/yws/res/...)

看似“导入成功”，实际完全不可用。直接控制桌面客户端或 Chromium 控制台也不可靠：数据量一大，页面、开发者工具和同步进程都可能崩溃。

最终改用有道官方的 YoudaoNote CLI。纯文字笔记使用原生 save，含本地图片的网页剪藏使用 clip-save，再通过 move 归档到目标目录。这样生成的是有道能够正常查看和编辑的原生笔记，而不是一坨 Markdown 字符串。

图片不需要追求无损。迁移时采用 75% 质量，并按格式选择合适的工具或编码器：

处理策略不是简单地把所有图片压一遍，而是先清理网页外壳，再压缩正文图片。对于单篇图片总量达到 15–70 MiB 的文章，进一步限制长边尺寸；超大 GIF 转为 75% 质量的动态 WebP。这样肉眼观感变化很小，但请求体积能降到官方接口可接受的范围。

发现第一次导入不可用后，没有在错误数据上继续打补丁，而是停止有道客户端同步，通过官方 CLI 删除已经到达云端的错误笔记，同时清理本地错误记录。

这次回滚共处理：

操作前保留了数据库备份。整个过程使用检查点记录已完成 ID，脚本中断或电脑关机后可以继续，而不会从头删除或重复创建。

这是后期最隐蔽的问题。

导入脚本曾把“CLI 返回成功并给出 fileId”理解为“笔记已经进入目标文件夹”。逐页读取云端目录并与检查点对账后发现：

根因是 save 命令创建成功后，目录参数并没有按预期生效；同时第一次清理期间仍有少量同步竞态，导致旧记录残留。

修复方案不是按标题猜测，而是完全基于两个检查点中的 fileId：

最终移动 2135 条、删除 679 条，错误为 0。正确归档数量达到 5005 条。

这次迁移最后稳定下来，依靠的不是某个神奇命令，而是一组朴素的工程措施：

迁移持续数小时，中间还经历了关机暂停。为了不用一直盯着终端，我封装了一个通用企业微信通知工具，支持普通消息和节流进度消息。修复阶段每增加 100 个操作或每 5 分钟推送一次，异常退出会自动从检查点重启并通知，完成时强制发送最终结果。

通知工具只从用户级私密配置读取 Webhook，密钥不会写进项目源码和日志。

最大的教训是：批量迁移不能只看接口返回值。真正的“完成”必须同时满足内容能正常阅读、图片能显示、目录位置正确，并且云端逐项对账通过。