告别平台绑定：用yuque-exporter实现语雀文档自主管理

你是否遇到过这样的困扰：语雀文档分散在不同知识库难以统一管理？担心平台政策变动导致文档丢失？需要将语雀内容迁移到本地或其他平台却缺乏高效工具？yuque-exporter正是为解决这些痛点而生的开源工具，让你轻松掌控知识资产的所有权与迁移自由。

【核心优势】五大能力矩阵

1. 全链路文档迁移

✓ 完整保留文档原始格式与排版
✓ 自动处理图片资源本地化存储
✓ 智能转换内部链接为相对路径

2. 增量更新机制

✓ 自动识别已导出文档
✓ 仅处理新增或修改内容
✓ 断点续传避免重复劳动

3. 目录结构复刻

✓ 1:1还原语雀知识库层级
✓ 支持多级目录嵌套
✓ 保持文档间逻辑关系

4. 多场景适配

✓ 个人知识库完整备份
✓ 团队协作文档批量迁移
✓ 多平台内容分发准备

5. 零成本部署

✓ 纯命令行操作无需图形界面
✓ 跨平台支持Windows/macOS/Linux
✓ 开源免费无功能限制

【准备工作】环境与资源检测

【环境检测】系统兼容性验证

node -v  # 检查Node.js版本（需v14.0.0以上）
# 预期输出：v16.14.2（示例版本）

npm -v   # 检查npm包管理器
# 预期输出：8.5.0（示例版本）

git --version  # 检查Git工具
# 预期输出：git version 2.34.1（示例版本）

注意：如命令未识别，请先安装Node.js（含npm）和Git工具。Node.js是运行JavaScript的环境，Git是代码版本管理工具，两者都是本工具的运行基础。

【资源准备】获取项目源码

git clone https://gitcode.com/gh_mirrors/yuqu/yuque-exporter  # 克隆项目仓库
cd yuque-exporter  # 进入项目目录
npm install  # 安装依赖包（仅首次运行需执行）
# 预期输出：added 128 packages in 15s（示例结果）

【实施流程】四步完成文档迁移

【令牌获取】创建API访问凭证

1. 登录语雀官网，点击右上角头像 → 「个人设置」
2. 在左侧导航栏找到「API令牌」选项
3. 点击「创建新令牌」，输入名称（如"文档导出工具"）
4. 复制生成的令牌字符串（形如abcdef123456...）

API令牌是用于身份验证的访问密钥，相当于你的语雀账号密码，请勿分享给他人。

【配置验证】环境变量设置

YUQUE_TOKEN=你的令牌字符串 npm start  # 启动导出程序
# 预期输出：[INFO] 开始初始化语雀API客户端...

注意：将命令中的"你的令牌字符串"替换为实际复制的API令牌，令牌与=之间不能有空格。

【执行导出】文档抓取过程

程序运行后将显示实时进度：

• 首先获取知识库列表
• 按层级遍历文档结构
• 逐个下载文档内容与图片
• 生成本地Markdown文件

[PROGRESS] 正在处理知识库：技术笔记 (32/56)
[PROGRESS] 已完成：API设计指南.md (1.2MB)
[PROGRESS] 图片处理：将 https://cdn.yuque.com/... 保存至 ./output/images/

【结果验证】导出文件检查

导出完成后，在项目目录下会生成output文件夹：

ls output  # 查看导出目录结构
# 预期输出：知识库1  知识库2  图片资源

cat output/知识库1/入门指南.md  # 查看文档内容
# 预期输出：文档Markdown内容预览...

【场景拓展】文档迁移决策指南

不同场景的适配策略

迁移场景	推荐操作	注意事项	适用工具参数
全量备份	首次完整导出	确保网络稳定	默认配置
增量更新	定期执行导出	无需额外参数	默认配置
选择性迁移	指定知识库ID	需提前获取ID	--repo=xxx
紧急备份	限制并发数	避免API限制	--concurrency=2

典型应用场景

场景一：个人知识管理系统构建

当你需要将分散在多个语雀知识库的内容整合到本地Obsidian或Notion时：

1. 执行完整导出获取所有文档
2. 通过output目录结构梳理知识体系
3. 导入到目标知识管理工具
4. 定期增量更新保持同步

场景二：团队文档归档

企业需要定期备份重要项目文档时：

1. 创建专用API令牌（限制只读权限）
2. 编写定时任务脚本自动执行
3. 将输出目录同步至企业存储
4. 验证备份完整性（可对比文件数量）

场景三：多平台内容分发

内容创作者需要将语雀文档发布到多个平台时：

1. 导出为标准Markdown格式
2. 使用格式转换工具适配各平台
3. 保留相对图片路径确保显示正常
4. 建立版本管理跟踪内容变更

【常见问题】解决方案速查

导出中断如何处理？

! 无需担心，重新执行导出命令即可自动跳过已完成文件，从上次中断处继续。

遇到API调用限制怎么办？

! 语雀API限制5000次/小时，可添加--delay=1000参数（单位毫秒）降低请求频率。

中文显示乱码如何解决？

! 确保系统编码为UTF-8，执行export LANG=en_US.UTF-8（Linux/macOS）或在环境变量中设置。

如何自定义输出目录？

! 修改src/config.ts文件中的outputDir配置项，支持绝对路径和相对路径。

【行动指南】立即掌控你的知识资产

现在你已经了解yuque-exporter的全部核心功能和使用方法。无论是为了摆脱平台依赖，还是建立多重备份保障，或是实现知识资产的跨平台流动，这款工具都能满足你的需求。

立即执行以下命令开始你的第一次文档导出：

git clone https://gitcode.com/gh_mirrors/yuqu/yuque-exporter && cd yuque-exporter && npm install
# 安装完成后执行：
YUQUE_TOKEN=你的令牌 npm start

让知识真正属于你自己，从掌控文档的存储与迁移开始。