语雀文档迁移与Markdown导出完全指南：5分钟上手的知识管理工具

2026-04-27 12:29:50作者：余洋婵Anita

为什么你需要这款工具？

当你发现语雀文档导出功能收费、团队需要批量迁移知识库、或者想将文档备份到本地时，yuque-exporter正是解决这些痛点的理想选择。这款开源工具支持文档批量处理与本地备份，让你的知识资产不再受平台限制，完全掌握在自己手中。

准备工作：5分钟环境配置

检查系统环境

在开始前，请确保你的系统已安装以下工具：

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

npm -v   # 检查npm版本，需v6.0.0以上
# 示例输出：8.5.0

git --version  # 检查Git是否安装
# 示例输出：git version 2.34.1

如果显示"command not found"，请先安装对应工具：

Node.js：前往官网下载LTS版本
Git：通过系统包管理器安装（如apt install git或brew install git）

获取项目代码

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

安装依赖包

npm install
# 示例输出：
# added 128 packages, and audited 129 packages in 15s
# found 0 vulnerabilities

💡 小贴士：遇到依赖安装失败？

如果npm install失败，尝试使用国内镜像： ```bash npm install --registry=https://registry.npm.taobao.org ```

快速上手：3步完成文档导出

第1步：获取语雀API令牌

登录语雀账号
进入「个人设置」→「API令牌」页面
点击「创建新令牌」，输入名称（如"yuque-exporter"）
复制生成的令牌（形如abcdef1234567890）

第2步：执行导出命令

YUQUE_TOKEN=你的令牌 npm start
# 执行过程示例：
# [INFO] 开始获取知识库列表...
# [INFO] 发现3个知识库，开始导出...
# [SUCCESS] 已导出文档: 15/23 (65%)
# [SUCCESS] 全部文档导出完成！

第3步：查看导出结果

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

output/
├── 知识库A/
│   ├── 目录1/
│   │   ├── 文档1.md
│   │   └── 文档2.md
│   └── 图片/
│       ├── image1.png
│       └── image2.jpg
└── 知识库B/
    └── 文档3.md

核心功能：解决你的实际问题

问题：图片无法本地访问

解决方案：自动下载图片并替换链接

原语雀图片链接：https://cdn.yuque.com/xxx.png
处理后链接：./图片/image1.png

问题：文档链接失效

解决方案：内部链接转为相对路径

原链接：https://www.yuque.com/xxx/yyy
处理后：../目录2/文档4.md

问题：格式混乱

解决方案：HTML标签自动清理

移除冗余样式标签
保留表格、代码块等关键格式
支持frontmatter元数据生成

高级配置：打造个性化导出方案

配置文件说明

核心配置文件为src/config.ts，主要参数如下：

参数	默认值	推荐值	说明
outputDir	'./output'	'./yuque-exports'	导出文件存放目录
concurrency	3	5	并发请求数量
timeout	30000	60000	请求超时时间(毫秒)
retry	2	3	失败重试次数

自定义导出命令

除环境变量方式外，也可使用命令行参数：

npx yuque-exporter --token=你的令牌 --output=./my-docs

🔧 展开查看更多命令参数

```bash --token, -t # 语雀API令牌（必填） --output, -o # 输出目录路径 --concurrency # 并发数 --include # 只导出指定知识库（逗号分隔） --exclude # 排除指定知识库（逗号分隔） ```

企业级应用：团队文档管理方案

批量账号管理

对于管理多个语雀账号的团队，可创建令牌配置文件tokens.json：

{
  "account1": "token1",
  "account2": "token2"
}

配合批量导出脚本：

for account in $(jq -r 'keys[]' tokens.json); do
  token=$(jq -r ".$account" tokens.json)
  YUQUE_TOKEN=$token OUTPUT_DIR="./output/$account" npm start
done

数据完整性校验

使用以下脚本检查导出是否完整：

# 安装校验工具
npm install -g markdown-validator

# 递归检查所有Markdown文件
markdown-validator --directory ./output

常见问题FAQ

Q: 导出过程中断后如何继续？
A: 工具支持增量导出，重新执行导出命令会自动跳过已完成文件。

Q: 遇到"API请求限制"错误怎么办？
A: 语雀API限制5000次/小时，可修改src/config.ts降低并发数：concurrency: 2

Q: 导出的Markdown在Obsidian中显示异常？
A: 在配置文件中设置obsidianCompatible: true，启用Obsidian兼容模式。

Q: 如何只导出特定知识库？
A: 使用命令行参数：npx yuque-exporter --token=xxx --include=知识库1,知识库2

功能	yuque-exporter	语雀官方导出	其他第三方工具
免费使用	✅ 完全免费	❌ 付费功能	❓ 部分免费
批量导出	✅ 支持	❌ 单知识库	⚠️ 有限支持
图片本地化	✅ 自动下载	❌ 需手动处理	⚠️ 部分支持
链接转换	✅ 相对路径	❌ 原链接保留	❌ 不支持
增量更新	✅ 支持	❌ 不支持	❌ 不支持
企业级功能	✅ 批量账号	❌ 无	❌ 无