语雀文档自由迁移：yuque-exporter完全掌握指南

为何需要文档迁移工具？

当你发现语雀文档只能在平台内查看，无法离线访问时；当团队需要将知识库迁移到自建系统时；当免费账户面临存储空间限制时——yuque-exporter正是解决这些痛点的理想工具。这款开源工具能将语雀文档批量转换为Markdown格式，让你的知识资产真正属于自己。

准备阶段：环境与工具准备

系统环境检查

yuque-exporter基于Node.js开发，首先确认你的系统已安装必要环境：

node -v  # 检查Node.js版本（需v14+）
npm -v   # 检查npm包管理器版本
git -v   # 检查Git版本控制工具

如果命令未找到或版本过低，请先安装/升级相应软件。Node.js推荐使用v16或更高版本以获得最佳兼容性。

获取项目代码

执行以下命令克隆项目仓库到本地：

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

安装依赖包

进入项目目录后，安装所需的依赖组件：

npm install

注意事项：如果安装过程中出现网络问题，可尝试使用npm镜像源加速：

npm install --registry=https://registry.npmmirror.com

执行阶段：从配置到导出的完整流程

配置API访问令牌

1. 登录语雀账号，进入「个人设置」→「API令牌」页面
2. 点击「创建新令牌」，输入名称（如"yuque-exporter"）并保存
3. 复制生成的令牌字符串，这将用于后续的API认证

执行文档导出

使用以下命令启动导出过程，将<你的令牌>替换为实际获取的API令牌：

YUQUE_TOKEN=<你的令牌> npm start

工具将自动开始抓取并处理文档，过程中会显示进度信息。默认情况下，所有文档会按语雀原有的目录结构组织。

小贴士：导出过程中可以随时按Ctrl+C中断，重新运行命令时工具会自动跳过已导出的文档，实现增量更新。

查看导出结果

导出的文件默认存放在项目的storage目录下，结构如下：

• storage/：主输出目录
  • <知识库命名空间>/：每个知识库单独的文件夹
    • assets/：文档中引用的图片等资源
    • *.md：Markdown格式的文档文件

优化阶段：自定义与高级应用

修改默认配置

打开src/config.ts文件可以调整导出参数：

export const config = {
  host: 'https://www.yuque.com',  // 语雀API地址
  token: process.env.YUQUE_TOKEN, // 从环境变量获取令牌
  outputDir: './storage',         // 输出目录，可修改为其他路径
  clean: false,                   // 是否清除历史数据，设为true会删除原有文件
  // ...其他配置
};

修改后需重新运行导出命令使配置生效。

命令行工具使用

除了环境变量方式，也可以直接使用命令行参数：

npx yuque-exporter --token=<你的令牌>

实用场景案例

场景一：个人知识库备份

# 每周日自动备份，保留30天历史
0 0 * * 0 YUQUE_TOKEN=xxx npm start && find ./storage -mtime +30 -delete

场景二：团队文档协作

# 导出特定知识库
YUQUE_TOKEN=xxx npm start -- user/repo1 user/repo2

场景三：静态站点生成

# 导出后直接生成HTML
YUQUE_TOKEN=xxx npm start && npx docsify serve storage

核心能力解析

智能内容处理

yuque-exporter不仅是简单的文件下载工具，它能：

• 图片本地化：自动下载文档中的图片并替换为本地路径
• 链接转换：将语雀内部链接转为相对路径，保持文档间跳转功能
• 格式清理：移除不必要的HTML标签，生成干净的Markdown
• 元数据保留：通过frontmatter保留文档标题、原始URL等信息

目录结构重建

工具会分析语雀的TOC（目录）信息，在本地重建相同的文件夹层次结构。这一过程通过src/lib/tree.ts实现，使用树形数据结构和UUID匹配确保目录关系的准确性。

常见误区解析

误区一：认为导出就是简单复制粘贴

实际情况：语雀使用自定义的文档格式，直接复制会丢失格式和图片。yuque-exporter通过解析API返回的结构化数据，进行专业的格式转换。

误区二：忽略API调用限制

实际情况：语雀API有调用频率限制（5000次/小时）。如遇限制，工具会自动暂停并重试，建议避免在短时间内频繁导出大量文档。

误区三：未验证导出完整性

最佳实践：导出完成后，应随机抽查几个文档，特别注意：

• 图片是否正确显示
• 表格和代码块格式是否完整
• 内部链接是否能正常跳转

进阶使用技巧

技巧一：自定义文档处理逻辑

修改src/lib/doc.ts中的buildDoc函数，可以添加自定义处理步骤，如：

• 添加自定义frontmatter字段
• 实现特殊格式转换
• 过滤不需要的内容

技巧二：集成到工作流

将导出过程集成到自动化流程：

# 在package.json中添加脚本
"scripts": {
  "export-docs": "YUQUE_TOKEN=xxx npm start",
  "deploy-docs": "npm run export-docs && git -C storage add . && git -C storage commit -m 'Update docs' && git -C storage push"
}

工具工作原理

yuque-exporter的工作流程分为三个主要阶段：

1. 数据爬取（crawler.ts）：通过语雀API获取文档元数据和内容
2. 结构构建（tree.ts）：分析TOC信息，建立文档间的层级关系
3. 内容处理（doc.ts）：转换格式、下载资源、修复链接

这三个阶段协同工作，确保从云端到本地的无缝迁移。

同类工具对比

特性	yuque-exporter	浏览器插件导出	手动复制粘贴
批量处理	✅ 支持	❌ 有限	❌ 不支持
图片本地化	✅ 自动	❌ 需手动	❌ 需手动
链接转换	✅ 智能转换	❌ 保留原链接	❌ 保留原链接
增量更新	✅ 支持	❌ 不支持	❌ 不支持
命令行操作	✅ 完全支持	❌ 不支持	❌ 不支持

社区与资源

• 代码仓库：项目源码托管在GitCode，欢迎提交Issue和PR
• 问题反馈：通过仓库的Issue系统报告bug或提出功能建议
• 版本更新：定期查看仓库的Releases页面获取最新功能
• 使用交流：可以在项目讨论区分享使用经验和技巧

总结

yuque-exporter为语雀用户提供了文档自主权，通过简单的命令即可将知识资产迁移到本地。无论是个人用户备份笔记，还是团队进行文档管理，这款工具都能显著提高工作效率。

随着项目的持续迭代，未来还将支持更多高级功能，如多账号管理、Obsidian集成等。现在就开始使用，让你的语雀文档真正为你所用！