三步完成语雀文档迁移：Markdown本地备份全攻略

副标题：告别平台依赖，用yuque-exporter打造你的知识保险箱

开篇：当团队知识库面临"断舍离"

上周接到通知：公司语雀团队空间即将到期，300+篇技术文档需要在7天内完成备份。作为团队里的"工具人"，我试了3种方案：手动复制粘贴（效率低）、官方导出功能（格式错乱）、第三方插件（付费且有数据风险）。最终，一个叫yuque-exporter的开源工具帮我们实现了"无痛迁移"——3行命令、2小时完成全量备份，连图片和内部链接都完美保留。

本文将用"问题-操作-验证"的实战框架，带你避开90%的迁移坑。

第一章：环境部署——5分钟搭好迁移工作站

⚠️ 常见误区

"直接用npx运行就能成功？"
不少用户忽略了Node.js版本兼容性，导致启动时报SyntaxError。

💡 正确操作

1. 系统准备（选择对应方式）

操作系统	安装命令	版本要求
macOS/Linux	brew install node 或 sudo apt install nodejs	Node.js ≥ 14.0.0
Windows	从nodejs.org下载LTS版本	需勾选"Add to PATH"

2. 获取数字钥匙（API Token）
登录语雀→右上角头像→「账号设置」→「开发者设置」→「创建Token」，复制生成的字符串（这串字符相当于你知识库的"电子钥匙"，不要分享给他人）。

3. 测试运行

# 首次使用（免安装）
npx yuque-exporter --token=你的密钥 --repo=用户名/知识库名

# 或本地安装（适合频繁使用）
npm install -g yuque-exporter
yuque-exporter --token=你的密钥 --repo=用户名/知识库名

✅ 效果验证

终端显示Export completed!，当前目录生成output文件夹，包含.md文件和images子目录。

第二章：核心功能——解锁3个生产力开关

⚠️ 常见误区

"导出的Markdown图片都是裂开的？"
这是因为忽略了图片本地化参数，默认配置仅导出文本。

💡 正确操作

1. 图片自动下载

yuque-exporter --token=密钥 --repo=用户名/知识库 --download-images

💡 技巧：添加--image-folder=assets可自定义图片存放目录，适配Hexo、VuePress等静态博客需求。

2. 目录结构自定义

yuque-exporter --token=密钥 --repo=用户名/知识库 --use-slug

🔍 说明：--use-slug参数会将中文目录名转为"URL友好标识符"（如"前端笔记"→"qian-duan-bi-ji"），解决Windows系统中文路径乱码问题。

3. 批量处理多知识库

yuque-exporter --token=密钥 --repo=用户名/知识库1,用户名/知识库2 --output=./backup

✅ 效果验证

output目录下按原语雀结构生成嵌套文件夹，Markdown中图片链接格式为描述。

第三章：问题排查——3分钟定位故障点

graph TD
    A[启动失败] -->|报错"Token invalid"| B[检查密钥是否过期]
    A -->|报错"Repo not found"| C[确认知识库路径格式：用户名/知识库名]
    D[导出后无内容] -->|仅生成空文件夹| E[检查网络代理设置]
    D -->|部分文档缺失| F[确认文档是否为"私密"状态]
    G[图片无法显示] --> H[添加--download-images参数]
    G --> I[检查output/images目录权限]

高频问题速查表

症状	病因	药方
终端显示403错误	Token权限不足	重新生成Token并勾选"读取知识库"权限
文件名含问号/星号	系统不支持特殊字符	添加--sanitize-filenames参数
内部链接404	文档ID变更	使用--fix-links修复相对路径

结语：不止于备份的知识管理工具

yuque-exporter最让我惊喜的是"增量更新"特性——第二次运行时只会同步变更内容，这对持续维护的知识库来说太实用了。目前项目还在快速迭代，作者承诺下个月会支持Obsidian的双链格式（期待ing）。

如果你也受困于平台锁定，不妨用这个工具把知识主权握在自己手里。毕竟，数据存在本地，安全感才是100%的。

📌 工具地址：gitcode.com/gh_mirrors/yuq/yuque-exporter（仅用于获取源码，实际使用无需克隆仓库）