三步完成语雀文档迁移：Markdown本地备份全攻略
项目地址: https://gitcode.com/gh_mirrors/yuq/yuque-exporter 副标题：告别平台依赖，用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分钟定位故障点
高频问题速查表
| 症状 | 病因 | 药方 |
|---|---|---|
| 终端显示403错误 | Token权限不足 | 重新生成Token并勾选"读取知识库"权限 |
| 文件名含问号/星号 | 系统不支持特殊字符 | 添加--sanitize-filenames参数 |
| 内部链接404 | 文档ID变更 | 使用--fix-links修复相对路径 |
结语：不止于备份的知识管理工具
yuque-exporter最让我惊喜的是"增量更新"特性——第二次运行时只会同步变更内容，这对持续维护的知识库来说太实用了。目前项目还在快速迭代，作者承诺下个月会支持Obsidian的双链格式（期待ing）。
如果你也受困于平台锁定，不妨用这个工具把知识主权握在自己手里。毕竟，数据存在本地，安全感才是100%的。
📌 工具地址：gitcode.com/gh_mirrors/yuq/yuque-exporter（仅用于获取源码，实际使用无需克隆仓库）
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
