语雀文档导出器：yuque-exporter 完整使用指南

项目概述

yuque-exporter 是一款专为语雀用户设计的批量文档导出工具，能够将语雀平台上的文档快速转换为本地 Markdown 格式。随着语雀从内容社区转型为创作工具并调整付费策略，这款免费开源工具为需要迁移个人博客的用户提供了便捷解决方案。

快速开始

环境准备

首先需要克隆项目到本地：

git clone https://gitcode.com/gh_mirrors/yuqu/yuque-exporter

安装依赖

cd yuque-exporter
npm install

获取语雀 Token

在使用 yuque-exporter 之前，您需要获取语雀的访问 Token：

1. 登录语雀官网
2. 进入个人设置中的"开发者管理"
3. 生成新的访问 Token 并妥善保存

核心功能详解

文档爬取机制

yuque-exporter 通过调用语雀 API 实现文档的批量获取。核心的爬取流程包括：

• 获取用户信息和仓库列表
• 解析仓库的目录结构（TOC）
• 下载文档详细内容
• 智能检测文档变更，避免重复下载

文件处理流程

工具对导出的文档进行多项处理：

• 支持 frontmatter 格式
• 自动下载图片和画板内容
• 替换文档链接为相对链接
• 清理多余的 HTML 标签

目录结构构建

根据语雀的目录结构（TOC），工具会在本地构建相应的文件目录。目前默认使用中文文件名，便于保持原有的组织架构。

使用方法

基础导出命令

设置环境变量并执行导出：

YUQUE_TOKEN=<your token> npm start

指定仓库导出

如果您只想导出特定的仓库，可以修改 src/main.ts 文件中的配置：

const urlPaths = [
  'your-username/your-repo-name',
  // 添加更多仓库路径
];

配置说明

主要配置参数

在 src/config.ts 文件中，您可以找到以下重要配置项：

• host: 语雀 API 地址
• token: 访问令牌
• outputDir: 输出目录
• clean: 是否清理元数据

输出目录结构

导出的文档将按照以下结构组织：

storage/
├── .meta/           # 元数据目录
│   ├── username/    # 用户信息
│   └── namespace/   # 仓库数据
└── output/          # 最终 Markdown 文件

常见问题解决

Token 配置问题

如果遇到认证失败，请检查：

1. Token 是否正确设置
2. Token 是否具有足够的权限
3. 网络连接是否正常

中文文件名处理

由于默认使用中文文件名，在某些文件系统中可能会遇到兼容性问题。建议：

• 检查系统对中文文件名的支持
• 如有需要，可手动修改文件名

草稿文件处理

草稿文档默认会直接放在根目录下，这样可以更好地维护相对链接的完整性。

高级功能

批量处理优化

工具支持并发下载，默认并发数为 10，可以有效提高导出效率。对于大型文档库，建议适当调整并发参数。

增量导出机制

yuque-exporter 具有智能的增量导出功能，只会下载发生变更的文档，大大减少了重复工作。

技术架构

项目采用 TypeScript 开发，主要依赖包括：

• consola: 日志输出
• fast-glob: 文件匹配
• p-queue: 任务队列管理
• remark: Markdown 处理

注意事项

1. API 调用限制：语雀 API 每小时限制 5000 次调用
2. 附件下载：由于需要登录权限，目前暂不支持附件下载
3. 多账号支持：当前版本主要针对个人账号，团队文档支持正在开发中

通过本指南，您可以快速掌握 yuque-exporter 的使用方法，顺利完成语雀文档的本地迁移工作。