语雀文档批量导出工具：一站式自动化迁移解决方案

语雀文档批量导出工具：一站式自动化迁移解决方案

【免费下载链接】yuque-exporterexport yuque to local markdown项目地址: https://gitcode.com/gh_mirrors/yuq/yuque-exporter

在语雀调整付费策略后，免费用户面临文档迁移的困境。yuque-exporter 是一款高效、轻量级的开源工具，专为开发者和技术爱好者设计，能够自动化批量导出语雀文档为本地 Markdown 文件，实现知识库的自主管理。通过调用语雀 API、智能处理文档结构和内容转换，该工具提供了完整的文档迁移解决方案，让您的技术文档、个人博客和团队知识库真正属于您自己。

📦 核心功能与架构设计

yuque-exporter 采用模块化设计，将文档导出流程分解为清晰的四个阶段：

整个工具的工作流程遵循以下自动化管道：

语雀 API 调用 → 元数据存储 → TOC 目录构建 → 内容处理 → 本地文件生成

🚀 快速开始：3分钟完成安装配置

环境准备与项目克隆

首先确保系统已安装 Node.js 16+ 和 Git，然后执行以下命令：

# 克隆项目仓库 git clone https://gitcode.com/gh_mirrors/yuq/yuque-exporter # 进入项目目录 cd yuque-exporter # 安装项目依赖 npm install

获取语雀 API Token

登录语雀平台后，进入"个人设置" → "API令牌"页面，创建新的令牌并复制保存。这是工具访问语雀数据的唯一凭证。

配置与运行

设置环境变量并启动导出流程：

# 设置环境变量并运行导出 YUQUE_TOKEN=your_token_here npm start

或者使用命令行参数方式：

# 使用 npx 直接运行（无需克隆项目） npx yuque-exporter --token=your_token_here

⚙️ 高级配置与自定义选项

配置文件详解

工具的核心配置位于 src/config.ts，支持以下自定义选项：

// 默认配置示例 export const config = { host: 'https://www.yuque.com', // 语雀域名 token: process.env.YUQUE_TOKEN, // API Token userAgent: 'yuque-exporter', // 请求标识 outputDir: './storage', // 输出目录 clean: false, // 是否清理旧文件 };

多仓库批量导出

通过修改启动参数，可以同时导出多个知识库：

// 在 src/main.ts 中配置要导出的仓库 const urlPaths = [ 'your_username/repo1', // 个人知识库 'your_username/repo2', // 另一个仓库 'team_name/repo3', // 团队知识库 ];

🔧 技术实现细节

文档处理流程

工具对每个文档执行以下处理步骤：

1. 内容解析：将语雀的 HTML 内容转换为标准 Markdown 格式
2. 图片下载：自动下载文档中的图片到本地，并更新链接
3. 链接替换：将语雀内部文档链接转换为相对路径
4. Frontmatter 生成：为每个文档添加元数据头部信息
5. 文件名规范化：处理中文文件名和特殊字符

目录结构重建

基于语雀的 TOC（目录）信息，工具会重建完整的目录层级：

# 示例目录结构 - 项目文档/ ├── 01-项目介绍.md ├── 02-快速开始/ │ ├── 安装指南.md │ └── 配置说明.md └── 03-API参考/ ├── 用户接口.md └── 数据接口.md

增量导出机制

工具支持断点续传和增量导出，避免重复下载已处理的文档：

// 核心增量逻辑实现 export async function build() { // 检查已存在的元数据 const existingMeta = await loadExistingMeta(); // 只处理新增或修改的文档 const docsToProcess = filterNewOrUpdatedDocs(existingMeta); // 批量处理文档 await processDocsInParallel(docsToProcess); }

📁 输出文件结构说明

导出完成后，您将在storage目录下看到以下结构：

storage/ ├── .meta/ # 元数据缓存目录 │ ├── docs.json # 文档元数据 │ └── toc.yaml # 目录结构信息 ├── 项目文档/ # 知识库根目录 │ ├── 01-项目介绍.md # 处理后的 Markdown 文件 │ ├── 02-快速开始/ │ │ ├── 安装指南.md │ │ └── 配置说明.md │ └── assets/ # 图片资源目录 │ └── image-1.png └── draft/ # 草稿文档目录 └── 未完成文档.md

🛠️ 常见问题与解决方案

导出过程中断处理

如果导出过程意外中断，重新执行命令即可继续：

# 工具会自动跳过已处理的文档 YUQUE_TOKEN=your_token npm start

API 调用频率限制

语雀 API 有每小时 5000 次的调用限制。工具内置了以下优化策略：

1. 请求队列管理：使用 p-queue 库控制并发请求
2. 智能重试机制：遇到限流时自动等待并重试
3. 进度保存：定期保存处理进度，避免重复工作

中文文件名处理

工具会自动处理中文文件名和特殊字符：

// 使用 filenamify 库处理文件名 import filenamify from 'filenamify'; const safeFileName = filenamify(chineseName, { replacement: '_' });

图片下载失败处理

对于需要登录才能访问的图片，工具会记录错误日志并继续处理其他内容，确保导出流程不会因单个图片失败而中断。

🔍 扩展与二次开发

插件系统架构

工具采用模块化设计，便于扩展新功能：

// 自定义处理器示例 export interface DocProcessor { name: string; process(doc: DocDetail): Promise<DocDetail>; } // 注册自定义处理器 registerProcessor({ name: 'custom-processor', process: async (doc) => { // 自定义处理逻辑 return processedDoc; } });

支持 Obsidian 格式

对于 Obsidian 用户，可以通过扩展工具支持双链笔记格式：

// Obsidian 链接转换示例 function convertToObsidianLinks(content: string): string { // 将 [[文档标题]] 转换为 Obsidian 链接格式 return content.replace(/\[\[([^\]]+)\]\]/g, '[[$1]]'); }

📈 性能优化建议

批量处理策略

对于大型知识库，建议采用分批导出策略：

# 分批导出不同仓库 YUQUE_TOKEN=your_token npm start -- --repo=repo1 YUQUE_TOKEN=your_token npm start -- --repo=repo2

内存使用优化

工具在处理大量文档时采用流式处理和分块写入，避免内存溢出：

// 流式写入示例 async function writeLargeDocument(content: string, filePath: string) { const stream = createWriteStream(filePath); // 分块写入，避免内存压力 await writeInChunks(stream, content); }

🎯 最佳实践指南

生产环境部署

对于团队使用，建议将工具部署到 CI/CD 流水线中：

# GitHub Actions 配置示例 name: Yuque Sync on: schedule: - cron: '0 2 * * *' # 每天凌晨2点自动同步 jobs: sync: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: Setup Node.js uses: actions/setup-node@v3 - name: Install dependencies run: npm ci - name: Export Yuque docs run: | YUQUE_TOKEN=${{ secrets.YUQUE_TOKEN }} npm start - name: Commit changes run: | git config --local user.email "action@github.com" git config --local user.name "GitHub Action" git add . git commit -m "Update docs" || echo "No changes to commit"

文档版本管理

导出的文档可以轻松集成到现有的版本控制系统中：

# 初始化 Git 仓库并提交文档 cd storage git init git add . git commit -m "Initial export from Yuque"

🏁 总结与展望

yuque-exporter 为语雀用户提供了一套完整、可靠的文档迁移解决方案。通过自动化批量导出、智能内容处理和灵活的配置选项，它解决了平台锁定问题，让知识资产真正掌握在用户手中。

未来版本计划增加更多高级功能，包括多账号支持、团队协作文档导出、以及与其他笔记工具的深度集成。项目的开源特性也欢迎社区贡献，共同打造更强大的文档管理工具生态系统。

无论您是个人开发者、技术团队还是知识管理爱好者，yuque-exporter 都能帮助您高效、安全地迁移和管理语雀文档，实现真正的知识自主。

【免费下载链接】yuque-exporterexport yuque to local markdown项目地址: https://gitcode.com/gh_mirrors/yuq/yuque-exporter