语雀笔记迁移到本地 Markdown

出于数据安全、离线访问、与本地知识库整合的考虑，需要把语雀上的笔记批量导出成本地 Markdown。最后用 yuque-dl 把几百篇文档连同图片一步到位拉下来，顺手还给这个工具补了一个「一键导出全部知识库」的功能并提了 PR。

背景

语雀（Yuque）是阿里旗下的在线知识管理工具，笔记存在云端。我的语雀空间包含 27 个私有知识库、共 360+ 篇文档，需要批量导出为本地 Markdown 文件。

方案对比

方案	工具	适合场景	优点	缺点
方案一	yuque-dl	批量下载整个知识库	自动下载图片、保留目录结构、支持增量更新	需要 Node.js、私有库需 cookie
方案二	官方导出 + yuque2markdown	不想装工具	官方支持	手动操作、.lakebook 转换可能丢格式
方案三	yuque-hexo	同步到 Hexo 博客	博客集成好	不适合纯本地归档
方案四	Open API 自编程	定制化需求	灵活	开发成本高

最终选择方案一 yuque-dl（2200+ star），最省心，图片和目录结构一步到位。

操作步骤

Step 1: 安装 yuque-dl

npm i -g yuque-dl
yuque-dl --version  # 确认安装成功

要求 Node.js 18.4+。

Step 2: 获取 Cookie（私有知识库必须）

语雀私有知识库需要登录凭证，获取步骤：

1. 浏览器登录语雀
2. 按 F12 打开开发者工具
3. 切到 Application（应用程序）标签页
4. 左侧 Cookies → 选择 https://www.yuque.com
5. 找到 _yuque_session，复制它的 Value

注意

Cookie 是登录凭证，等同于密码，不要泄露，用完即弃。

Step 3: 下载

方式一：下载单个知识库

yuque-dl "https://www.yuque.com/<用户名>/<知识库slug>" \
  -t "<cookie值>" \
  -d "<输出目录>" \
  --hideFooter

方式二：一键下载所有知识库（推荐）

# 自动枚举当前账号的所有知识库并逐个下载
yuque-dl user -t "<cookie值>" -d "/path/to/output"

内部通过 GET /api/mine/books 获取知识库列表，无需手动查找 slug。

方式三：批量下载指定的多个知识库

# 指定多个知识库 URL
yuque-dl batch "<url1>" "<url2>" "<url3>" \
  -t "<cookie值>" \
  -d "/path/to/output" \
  --hideFooter

方式四：下载单个或多个文档

# 下载单篇文档
yuque-dl doc "https://www.yuque.com/<用户名>/<知识库slug>/<文档slug>"

# 下载多篇文档
yuque-dl doc "<url1>" "<url2>"

常用参数

参数	说明
-t <token>	cookie 值（私有库必须）
-d <dir>	输出目录，默认 download。工具会自动在此目录下创建知识库名子目录
-i	忽略图片不下载
--hideFooter	不在文档底部加页脚（更新时间、原文链接）
--incremental	增量下载，只下载新增/更新的文档
--ignoreAttachments	忽略附件（可指定后缀如 mp4,pdf）
--toc	输出文档目录树
-p <password>	公开密码访问的知识库密码

实际迁移结果

项目	数量
知识库	27 个
Markdown 文档	368 篇
图片文件	1,026 张
总大小	318 MB
耗时	~4 分钟

每个知识库一个文件夹，保留原始层级。

开源贡献

迁移过程中发现 yuque-dl 原本不支持一键导出所有知识库，于是向原项目提了 PR：PR #102，新增 user 和 batch 子命令。

文件	改动
src/api.ts	新增 getUserBooks() — 调用 /api/mine/books 枚举知识库
src/index.ts	新增 downloadBooksFromUrls() 和 downloadAllBooks()
src/cli.ts	注册 batch 和 user 子命令
README.md	文档和 feature checklist

user 和 batch 命令在 PR 合并前可通过 fork 仓库本地构建使用。

踩坑记录

1. yuque-dl 只接受知识库 URL，不接受用户空间 URL — https://www.yuque.com/用户名 会报 No found book id，必须用 https://www.yuque.com/用户名/知识库slug。
2. API 枚举需要登录 — api/mine/books 接口带 cookie 才能返回数据，不带 cookie 返回 401。
3. Cookie 会过期 — _yuque_session 有效期有限，批量下载时如果报 401 需要重新获取。
4. -d 参数是父目录 — 工具会自动在 -d 目录下创建知识库名子目录。例如 -d ./语雀 会生成 ./语雀/毕设/...，不要传 -d ./语雀/毕设，否则会变成 ./语雀/毕设/毕设/...。
5. 建议限速 — 批量下载时每个知识库间隔 1-2 秒，避免触发语雀的风控机制。
6. 代理环境注意 — 如果设置了 HTTP_PROXY/HTTPS_PROXY，语雀作为国内服务建议加 NO_PROXY='yuque.com' 绕过代理，否则可能返回 410 错误。

后续维护

• Obsidian 阅读：直接用 Obsidian 打开导出目录作为 vault。
• 增量同步：yuque-dl "url" -t "cookie" -d "dir" --incremental，或等 user 命令合并后 yuque-dl user -t "cookie" -d "dir" --incremental。
• 跨平台迁移：Markdown 是通用格式，可直接导入 Notion、Logseq 等平台。