有道云笔记高效迁移方案：基于PicGo与PicList的Markdown导出实践

1. 为什么你需要迁移有道云笔记？

如果你和我一样，是个重度笔记用户，在有道云笔记里攒了几百甚至几千篇笔记，那你肯定也经历过那种“想走又不敢走”的纠结。笔记软件用久了，数据就成了“人质”。我当初决定迁移，导火索很简单：某天突然发现，想把我精心整理的Markdown笔记分享给用其他软件的朋友时，格式全乱了，图片更是直接“裂开”。那一刻我意识到，我的知识被锁在了一个封闭的“花园”里。

更深层的原因是，作为技术人，我们追求的应该是数据的自主权和格式的通用性。有道云笔记的存储格式是私有的，虽然它在线编辑体验不错，但一旦你想把笔记放到自己的博客、GitHub仓库，或者迁移到Obsidian、Typora、思源笔记这类以Markdown为核心的软件里，图片链接就成了最大的拦路虎。它的图片是存在自己的服务器上的，一旦离开有道云的环境，这些链接就失效了。手动一篇篇下载图片、修改链接？对于几十篇笔记或许可行，但面对我这种3000多篇的“庞然大物”，这无异于愚公移山。

所以，一个自动化的、能批量处理图片并转换链接的迁移方案，就成了刚需。我们的目标很明确：把有道云笔记里的内容，原汁原味（包括排版和图片）地导出为标准Markdown文件，并且所有图片都托管在一个我们自己可控的、稳定的图床上。这样生成的Markdown文件，你复制到任何支持Markdown的平台上，都能完美显示，真正实现“一次编写，处处可用”。

2. 迁移方案核心：PicGo与PicList如何分工？

要实现这个目标，我们需要两个核心工具：PicGo 和 PicList。很多朋友刚开始会搞混它俩的关系，我这里用个简单的类比帮你理清：

你可以把 PicGo 想象成一个功能强大、但需要图形界面操作的“图片上传管家”。它支持十几种图床（比如GitHub、Gitee、又拍云、七牛云等），你可以在它的图形界面里方便地拖拽上传图片，它会自动生成Markdown格式的图片链接。但对于我们这种需要命令行调用、批量自动化处理的场景，纯GUI的PicGo就有点使不上劲了。

这时，PicList 就登场了。你可以把它理解为 PicGo的“无头模式”或“API服务器版本”。它继承了PicGo所有的核心上传功能，但额外提供了一个关键的 HTTP API 服务。这意味着，任何程序（比如我们的迁移脚本）都可以通过发送一个HTTP请求，把图片数据传给PicList，PicList就会像PicGo一样，把图片上传到你配置好的图床，并把最终的图片URL返回给你。

所以，在我们的迁移流水线里，分工是这样的：

1. 迁移脚本（如 youdaonote-pull）：负责从有道云笔记拉取原始的笔记内容和图片。
2. PicList：作为图片上传中间件，接收脚本传来的图片，执行上传到指定图床的任务。
3. 图床（如GitHub、对象存储OSS等）：图片最终的存储地。

这个架构的精妙之处在于解耦。迁移脚本只负责“拆”（提取内容），PicList负责“运”（上传图片），图床负责“存”。无论你以后换什么图床，只需要在PicList里改一下配置，迁移脚本一行代码都不用动。

注意：网上有些教程会教你直接修改迁移脚本，让它调用PicGo的CLI。实测下来非常麻烦，因为涉及到环境变量、命令行参数等一系列问题。而PicList的HTTP API方案，是更标准、更稳定的工业级做法。

3. 手把手搭建你的迁移环境

理论说再多不如动手做一遍。下面我就带你从零开始，把整个环境搭起来。我的主力机是Windows，但为了覆盖更多朋友，我会同时说明Linux（以Ubuntu为例）下的关键步骤。

3.1 第一步：部署核心引擎 PicList

PicList是整套流程的枢纽，必须先把它跑起来。

在Windows上（最简单）： 直接去PicList的GitHub发布页，下载最新的 PicList-Setup-x.x.x.exe 安装包，像安装普通软件一样安装即可。安装完成后，PicList会默认开机自启，并在系统托盘运行。你右键托盘图标，选择“打开详细窗口”，就能看到它的Web管理界面和最重要的信息：API监听地址，通常是 http://127.0.0.1:36677。

在Linux服务器上（更稳定）： 如果你希望迁移任务在后台长期稳定运行，或者你的笔记库特别大，我强烈建议把PicList部署在一台Linux服务器上。

# 1. 下载PicList的Linux版本（以amd64为例）
wget https://github.com/Kuingsmile/PicList/releases/download/vx.x.x/PicList-vx.x.x-linux-amd64.tar.gz

# 2. 解压
tar -zxvf PicList-vx.x.x-linux-amd64.tar.gz

# 3. 进入目录，赋予执行权限
cd PicList
chmod +x PicList

# 4. 使用systemd创建后台服务（确保长期运行）
sudo nano /etc/systemd/system/piclist.service

将以下内容写入 piclist.service 文件：

[Unit]
Description=PicList Service
After=network.target

[Service]
Type=simple
User=你的用户名
WorkingDirectory=/path/to/PicList
ExecStart=/path/to/PicList/PicList
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

保存后，启动并设置开机自启：

sudo systemctl daemon-reload
sudo systemctl start piclist
sudo systemctl enable piclist

现在，你的PicList服务就在 http://你的服务器IP:36677 上运行了。可以通过 sudo systemctl status piclist 查看状态。

3.2 第二步：配置PicList的图床

PicList跑起来了，但它还不知道要把图片传到哪里。我们需要给它配置一个图床。这里我以GitHub作为示例，因为它免费、稳定，并且非常适合搭配Markdown笔记做版本管理。

1. 在PicList的Web界面（http://127.0.0.1:36677），点击左侧的“图床设置”。
2. 找到“GitHub图床”，点击“设为默认图床”。
3. 填写配置信息：
   • 仓库名：你的GitHub用户名/仓库名，例如 yourname/notes-images。
   • 分支：通常填 main。
   • Token：这是最关键的一步。你需要去GitHub -> Settings -> Developer settings -> Personal access tokens -> Tokens (classic) 生成一个。勾选 repo 权限即可。把这个token复制过来。
   • 存储路径：可以填写如 blog/，这样图片就会上传到仓库的 blog 目录下。
   • 自定义域名：如果你使用了GitHub Pages，可以填 https://cdn.jsdelivr.net/gh/yourname/notes-images@main 来加速访问。否则留空即可。

填好后，点击“确定”保存。你可以点击“测试”按钮，上传一张图片试试，成功后去你的GitHub仓库看看，图片应该已经在了。

踩坑提醒：免费图床都有容量或流量限制。比如Gitee，我最初用的就是它，结果在迁移了快2G图片后，仓库直接被封禁了。GitHub虽然也有单仓库1G的软限制，但相对宽松，社区方案成熟。对于超大型笔记库，更专业的做法是使用对象存储OSS（如阿里云OSS、腾讯云COS），它们价格低廉，按量付费，几乎没有容量上限，并且自带CDN加速。在PicList里配置OSS和其他商业图床也非常方便。

3.3 第三步：准备迁移脚本

这里我使用的是由 wade1010 维护的 youdaonote-pull 项目，它是对原始项目的一个功能增强版，原生支持了PicList。

# 克隆项目
git clone https://github.com/wade1010/youdaonote-pull.git
cd youdaonote-pull

# 安装Python依赖
pip install -r requirements.txt

项目根目录下有一个 config.json 文件，这是整个迁移的“大脑”。我们需要重点配置它。

4. 核心配置详解：让脚本与PicList联动

打开 config.json，你会看到很多配置项。我们聚焦在最关键的几个上：

{
  "username": "你的有道云笔记登录邮箱",
  "password": "你的有道云笔记密码",
  "local_dir": "./youdaonote", // 笔记导出后存放的本地目录
  "ydnote_dir": "/", // 从有道云笔记的哪个目录开始拉取
  "smms_secret_token": "", // 如果你不用SM.MS，这里留空
  "picgo_api": "http://127.0.0.1:36677/upload", // 核心！指向你的PicList API
  "picgo_args": {
    "list": [{
      "name": "image",
      "type": "file",
      "field": "image"
    }]
  },
  "is_relative_path": false, // 设置为false，让链接使用图床的绝对URL
  "disable_pic_list": false // 必须为false，启用图片上传功能
}

picgo_api 是这个配置的灵魂。它告诉迁移脚本：“嘿，兄弟，我提取出来的图片，都往这个地址送”。如果你把PicList部署在远程服务器上，这里就改成 http://你的服务器IP:36677/upload。

is_relative_path 设置为 false 至关重要。如果设为 true，生成的Markdown图片链接会是 ![](./image.jpg) 这样的相对路径，这只在你的本地文件夹里有意义。一旦你把笔记文件挪个地方，或者分享给别人，图片就又裂了。设为 false 后，脚本会请求PicList上传图片，并用PicList返回的完整的、指向图床的HTTP/HTTPS链接替换原链接，比如 ![](https://cdn.jsdelivr.net/gh/yourname/notes-images/blog/xxxx.jpg)。这样，这个链接在任何地方都能访问。

配置好后，保存文件。在运行前，我强烈建议你先做一次试运行，只拉取一两篇笔记看看效果。

# 试运行，只拉取指定目录下的前2条笔记
python pull.py --limit 2

去 local_dir 指定的目录下，打开生成的Markdown文件，检查图片链接是否已经变成了你的图床链接，并且图片能正常显示。如果一切正常，恭喜你，最复杂的部分已经完成了！

5. 处理迁移中的疑难杂症

迁移几千篇笔记不可能一帆风顺。下面是我在实战中踩过的坑和解决方案。

5.1 网络问题与重试机制

有道云笔记的服务器有时不太稳定，或者你的网络会有波动，导致某篇笔记或某张图片拉取失败。youdaonote-pull 脚本本身有一定的错误处理和重试，但对于大规模迁移，我建议你这样做：

• 分目录迁移：不要一次性拉取根目录/。先在有道云笔记网页版里，把你庞大的笔记库分成几个逻辑文件夹（比如“技术”、“生活”、“工作”）。然后在 config.json 里修改 ydnote_dir，一个文件夹一个文件夹地迁移。这样即使中途出错，你也知道从哪里继续。
• 使用日志：运行脚本时，把输出重定向到日志文件，方便排查。

  python pull.py > migration.log 2>&1
  

• 手动处理失败项：查看日志，如果有个别笔记始终失败，可以记下它的标题或ID。后续可以尝试单独拉取，或者干脆手动从网页版复制粘贴。不要因为1%的失败而放弃99%的自动化成果。

5.2 图片上传失败与PicList排查

如果笔记文字导出了，但图片全是裂的，问题大概率出在PicList环节。

1. 检查PicList服务状态：在浏览器访问 http://你的PicListIP:36677，看管理界面能否打开。
2. 检查图床配置：在PicList的Web界面，再次点击“测试上传”，确认当前配置的图床是通的。
3. 查看PicList日志：PicList的Web界面有“上传日志”页面，这里会记录每一次上传请求的详情，包括成功或失败的原因。如果看到“403 Forbidden”之类的错误，通常是GitHub Token权限不对或过期了；如果看到“413 Request Entity Too Large”，可能是图片太大，超过了图床限制。
4. 注意图片格式：有些图床对WebP等较新格式支持可能有问题。如果遇到奇怪格式的图片上传失败，可以考虑在PicList的“设置”中开启“图片压缩”或“格式转换”功能，在上传前自动将图片转为常见的JPEG/PNG格式。

5.3 迁移后的整理与优化

全部迁移完成后，你本地会有一个装满Markdown文件和图片的文件夹。但这还不是终点。

• 链接校验：你可以写一个简单的Python脚本，遍历所有Markdown文件，用正则表达式提取出所有图片链接，然后用 requests 库去逐个检查链接是否有效（返回状态码200）。这样可以批量找出“死链”。
• 文件重命名：有道云笔记导出的文件名可能包含中文或特殊字符。虽然现在系统兼容性好了，但为了保险起见，你可以用脚本将文件和文件夹名批量替换为英文或拼音。
• 导入新笔记系统：现在，你可以把这些纯净的、带绝对图片链接的Markdown文件，轻松地导入到Obsidian、Typora、思源笔记、Notion（通过Markdown导入）等任何你喜欢的工具中。知识的大门从此对你完全敞开。

6. 进阶玩法：打造更稳健的图片存储方案

如果你像我一样，有3000多篇笔记，图片总量好几个G，那么免费图床的限制很快就会碰到。这里分享我的进阶方案。

策略：多图床负载均衡 + 对象存储OSS PicList有一个强大功能叫自定义图床和负载均衡。你可以在PicList里配置多个图床，比如一个GitHub，一个Gitee，再加一个阿里云OSS。然后设置上传策略，比如“按顺序使用”或“随机使用”。

更专业的做法是，主力使用对象存储OSS。以阿里云OSS为例，购买一个资源包（40G一年也就几十块钱），对于个人笔记存储来说几乎等于无限容量和流量。在PicList里配置好OSS后，它的可靠性、速度和成本，都远非免费图床可比。

具体配置就是在PicList的“图床设置”里添加“阿里云OSS”，填写Endpoint、Bucket、AccessKey等信息即可。之后所有图片都会上传到你的OSS，获得一个形如 https://your-bucket.oss-cn-hangzhou.aliyuncs.com/image.jpg 的永久链接。

迁移完成后，看着本地整洁的Markdown文件夹，以及图床上井然有序的图片，那种对个人数据完全掌控的感觉，是使用任何云笔记软件都无法给予的。这套基于PicGo和PicList的方案，不仅解决了我从有道云笔记迁移的燃眉之急，更成为我日后所有数字内容管理的标准流程——任何需要处理图片和Markdown的场景，它都能派上用场。