yuque-exporter：3步实现语雀文档数据迁移与Markdown导出

一、工具概述

yuque-exporter是一款开源的语雀文档批量导出工具，专为需要将语雀知识库迁移到本地的用户设计。该工具能够将语雀文档完整转换为Markdown格式，并保持原有的目录结构，同时自动处理图片链接转换、内部链接调整和HTML标签清理等关键问题。适用于个人知识库迁移、团队文档备份以及多平台内容发布等场景，帮助用户实现知识资产的自主管理与跨平台流动。

二、准备工作

🔧 环境配置

在使用yuque-exporter前，需确保系统已安装以下依赖环境：

依赖项	版本要求	检查命令
Node.js	v14.0.0+	node -v
npm	v6.0.0+	npm -v
Git	任意版本	git --version

若未安装上述工具，请先通过官方渠道获取并安装。

🔑 获取API令牌

1. 登录语雀账号，进入个人设置 → API令牌页面
2. 点击"创建令牌"，设置令牌名称和权限范围
3. 生成后立即复制并保存令牌（关闭页面后无法再次查看）

📦 安装工具

通过以下命令获取并安装yuque-exporter：

# 克隆项目仓库
git clone https://gitcode.com/gh_mirrors/yuqu/yuque-exporter

# 进入项目目录
cd yuque-exporter

# 安装依赖包
npm install

三、核心功能

📥 基础导出功能

功能描述：通过命令行快速导出语雀文档，支持全量或增量导出

操作命令：

# 使用环境变量方式（推荐）
YUQUE_TOKEN=<您的令牌> npm start

# 或使用命令行参数方式
npx yuque-exporter --token=<您的令牌>

效果说明：

• 导出文件默认存放在项目根目录的output文件夹
• 文档按原知识库结构自动创建目录层级
• 已导出文件会被标记，再次运行时自动跳过

📷 媒体资源处理

功能描述：自动下载文档中的图片资源并转换为本地引用

效果说明：

• 图片自动保存至output/assets目录
• Markdown中的图片链接自动替换为相对路径
• 支持常见图片格式（jpg、png、gif等）

🔗 链接转换

功能描述：将语雀内部链接转换为本地相对路径

效果说明：

• 文档间引用自动调整为Markdown相对路径格式
• 锚点链接保持原功能不变
• 外部链接保持原始URL

四、高级应用

⚙️ 配置自定义

功能描述：通过修改配置文件调整导出行为

配置文件路径：src/config.ts

参数名	类型	默认值	说明
outputDir	string	'./output'	导出文件存放目录
concurrency	number	5	并发请求数量
timeout	number	30000	请求超时时间（毫秒）
retry	number	3	请求失败重试次数

🤖 自动化脚本示例

功能描述：通过脚本实现定期自动备份

创建auto-export.sh文件：

#!/bin/bash
# 语雀文档自动导出脚本

# 配置参数
TOKEN="your_api_token_here"
EXPORT_PATH="/path/to/backup/directory"
LOG_FILE="$EXPORT_PATH/export.log"

# 创建目录
mkdir -p $EXPORT_PATH

# 执行导出
cd /path/to/yuque-exporter
YUQUE_TOKEN=$TOKEN OUTPUT_DIR=$EXPORT_PATH npm start >> $LOG_FILE 2>&1

# 保留最近30天备份
find $EXPORT_PATH -type f -mtime +30 -delete

添加执行权限并设置定时任务：

# 添加执行权限
chmod +x auto-export.sh

# 设置每日凌晨执行
crontab -e
# 添加以下行
0 0 * * * /path/to/auto-export.sh

五、对比同类工具

特性	yuque-exporter	语雀官方导出	其他第三方工具
批量导出	✅ 支持	❌ 不支持	部分支持
目录结构保留	✅ 完整保留	❌ 不支持	基本支持
图片本地化	✅ 自动下载	❌ 仅链接	部分支持
增量导出	✅ 支持	❌ 不支持	大多不支持
API令牌认证	✅ 支持	❌ 需手动操作	部分支持
开源免费	✅ 完全开源	✅ 免费但功能有限	部分收费

六、常见问题

❓ 导出过程中断如何处理？

解决方案：直接重新执行导出命令，工具会自动跳过已完成的文件，继续未完成的任务。

❓ 遇到API调用限制怎么办？

解决方案：语雀API限制为5000次/小时，可通过修改src/config.ts中的concurrency参数降低并发数，或等待一小时后再试。

❓ 中文显示乱码如何解决？

解决方案：确保系统环境编码为UTF-8，可在终端执行以下命令：

export LANG=en_US.UTF-8

七、扩展开发指南

🛠️ 核心模块说明

yuque-exporter采用模块化设计，主要功能模块包括：

• 文档爬取：src/lib/crawler.ts - 负责从语雀API获取文档数据
• 内容处理：src/lib/doc.ts - 处理文档内容转换与清洗
• 目录构建：src/lib/tree.ts - 生成本地目录结构
• 工具函数：src/lib/utils.ts - 提供通用辅助功能

🚀 功能扩展建议

1. 多账号支持：修改src/lib/sdk.ts中的SDK类，添加多账号管理逻辑
2. 自定义格式转换：扩展src/lib/builder.ts，添加新的输出格式支持
3. UI界面：基于现有核心功能，使用Electron或React构建图形界面

🤝 贡献代码

1. Fork项目仓库
2. 创建特性分支：git checkout -b feature/amazing-feature
3. 提交修改：git commit -m 'Add some amazing feature'
4. 推送到分支：git push origin feature/amazing-feature
5. 提交Pull Request

八、总结

yuque-exporter提供了一种可靠、高效的语雀文档迁移解决方案，通过简单的命令即可实现知识库的完整导出。其模块化设计不仅保证了工具的稳定性和可维护性，也为用户提供了扩展定制的可能性。无论是个人用户还是团队，都能通过该工具实现知识资产的自主管理，摆脱平台限制，实现数据的自由流动。

通过本文介绍的方法，您可以快速掌握工具的使用技巧，并根据实际需求进行定制化配置。如有任何问题或建议，欢迎参与项目贡献或提交issue反馈。