🚩语雀知识库下载工具-全面使用指南

摘要

📦 一、工具简介与核心功能 yuque-dl 是一个开源的命令行工具，核心功能是将在线语雀知识库完整下载到本地，并转换为结构化的Markdown文件，同时保留图片等资源。为了让你快速了解它能做什么，可以参考下表：功能类别具体说明完整导出将知识库的文档树、文章内容完整导出为本地Markdown。资源处理支持将文章内的图片、附件一并下载到本地。特...

📦 一、工具简介与核心功能

yuque-dl 是一个开源的命令行工具，核心功能是将在线语雀知识库完整下载到本地，并转换为结构化的Markdown文件，同时保留图片等资源。

为了让你快速了解它能做什么，可以参考下表：

功能类别	具体说明
完整导出	将知识库的文档树、文章内容完整导出为本地Markdown。
资源处理	支持将文章内的图片、附件一并下载到本地。
特殊场景	支持下载私有、需密码访问或企业版的知识库。
体验优化	支持断点续传、生成文档目录(TOC)、启动本地预览服务等。

⚙️ 二、准备工作：安装Node.js与工具

1. 安装Node.js环境

这是运行 yuque-dl 的前提。

版本要求：确保安装 Node.js 18.4 或更高版本。
下载安装：访问 Node.js官网下载安装包，按提示完成安装。
配置镜像（可选但推荐）：为提升安装速度，可在命令行执行以下命令，将npm源设置为国内镜像：
```
npm config set registry https://registry.npmmirror.com
```

2. 安装yuque-dl工具

在命令行中执行以下命令进行全局安装：

npm i -g yuque-dl

🚀 三、基础使用：下载公开知识库

对于完全公开的知识库，下载命令非常简单。

复制知识库URL：在浏览器中打开目标知识库，复制地址栏的完整URL。
执行下载命令：在命令行中运行以下命令（将引号内替换为你的URL）：
```
yuque-dl "https://www.yuque.com/yuque/thyzgp"
```
查看下载结果：工具会自动在当前目录下创建 download/知识库名称/ 文件夹，所有Markdown文档和资源都会保存在这里。

🔐 四、高级使用：下载私有/加密知识库

下载私有、需要密码访问或企业版知识库时，需要提供身份验证凭证（Token）。

1. 如何获取Token（关键步骤）

Token本质上是浏览器Cookie的值。获取方法如下：

在Chrome或Edge浏览器中登录语雀，并访问你能浏览的那个私有知识库或加密文档页面。
按 F12 打开“开发者工具”。
切换到 “应用” (Application) 或 “存储” (Storage) 标签页。
在左侧找到 “Cookie” 选项，并点击其下的 https://www.yuque.com。
在右侧列表中找到名为 _yuque_session 的Cookie，并双击复制其“值”。这个长字符串就是你的Token。

注：对于企业版语雀（非yuque.com域名），Cookie的Key可能不是 _yuque_session，需要你在上述列表中自行查找确认，并使用 -k 参数指定。

2. 使用Token进行下载

获取Token后，在下载命令后加上 -t 参数即可：

yuque-dl "https://www.yuque.com/xxx/yyy" -t "你复制的_token_值"

重要提示：如果Token值以连字符（-）开头，直接使用会报错。需使用 -t="你的Token" 的格式，例如 -t="-a123"。

⚡ 五、实用功能与参数详解

yuque-dl 提供了丰富的参数来定制下载行为，以下是常用参数速查表：

参数	缩写	说明与示例
`--distDir <dir>`	`-d`	指定下载目录。例：`-d my_docs`
`--ignoreImg`	`-i`	不下载文章中的图片。
`--ignoreAttachments`	-	不下载附件。可指定后缀：`--ignoreAttachments mp4,pdf`。
`--toc`	-	在文档中生成目录（Table of Contents）。
`--incremental`	-	增量下载模式，只下载新内容，第二次下载时使用。
`--hideFooter`	-	隐藏文档末端的“更新时间、原文地址”页脚。
`--help`	`-h`	查看完整的帮助信息。

场景示例：只想下载文字和目录，忽略所有媒体文件，并保存到指定文件夹：

yuque-dl "知识库URL" -t="你的Token" -d "pure_text" --toc -i --ignoreAttachments

🖥️ 六、本地预览与内容管理

下载的知识库，可以用工具内置的VitePress服务进行优雅的本地预览。

在命令行中，进入你下载的知识库文件夹的上一层目录。

执行以下命令启动服务：

yuque-dl server ./download/你的知识库文件夹名/

根据提示在浏览器中打开 http://localhost:5173，即可获得一个界面清晰的本地网站来浏览内容。

⚠️ 七、常见问题与排错（FAQ）

Q：下载中途网络中断怎么办？
A：直接重新运行相同的下载命令。工具支持断点续传，已下载的内容不会重复下载。
Q：下载公开知识库的附件失败？
A：部分公开知识库的附件也需要登录权限。请尝试按照上述方法获取Token并加入命令中再次下载。
Q：如何确认Node.js版本？
A：在命令行输入 node -v 并回车，即可显示当前版本。
Q：命令执行后没有任何反应或报错？
A：首先检查知识库URL是否用英文引号包裹；其次，如果是私有库，请务必确认Token正确且使用了正确的格式。