1. 项目概述为什么我们需要批量导出语雀文档作为一名长期依赖语雀进行知识管理和团队协作的深度用户我几乎把所有的工作笔记、项目文档和技术沉淀都放在了上面。语雀的编辑器体验、知识库结构和协同功能确实做得不错但随着内容越积越多一个现实且紧迫的问题就浮出水面了数据安全与自主性。你可能会说语雀不是有官方的导出功能吗没错它支持单篇文档导出为Markdown、PDF等格式。但当你面对一个包含数百篇文章、结构复杂的知识库时一篇篇手动点击“导出”不仅耗时耗力更是一种精神折磨。更重要的是这种“手动”操作存在巨大风险网络波动、浏览器卡顿、甚至误操作都可能导致导出中断或遗漏。一旦你需要迁移平台、进行本地备份或者只是想用自己熟悉的工具如Obsidian、Typora、VS Code来离线编辑和检索这种低效的方式就成了拦路虎。因此“语雀批量导出MarkDown文件”这个需求本质上是一个数据资产回收与风险管理的过程。它不是为了“逃离”某个平台而是为了确保个人或团队的核心数字资产——知识——的绝对安全与可移植性。通过自动化脚本我们可以将散落在云端的结构化文档高效、完整、保真地“下载”到本地形成一个结构清晰的Markdown文件仓库。这之后无论是用Git进行版本管理用本地搜索工具进行全文检索还是进行二次加工和发布主动权都完全掌握在自己手中。2. 核心思路与技术选型解析要实现批量导出我们不能依赖图形界面必须通过程序与语雀的后台API进行交互。整个流程可以拆解为几个核心环节身份认证、文档遍历、内容获取与本地化存储。技术路线的选择直接决定了工具的稳定性、易用性和可维护性。2.1 为什么选择官方API而非模拟爬虫首先我们必须明确一个原则优先使用官方提供的合法接口。语雀为开发者提供了完善的Open API。相比于直接抓取网页Web Scraping使用API有压倒性优势稳定性高API接口稳定数据结构清晰不易因前端页面改版而失效。效率高直接获取JSON格式的纯数据无需解析复杂的HTML速度快节省带宽。合规合法在速率限制内使用是受平台支持的行为避免了因频繁爬取被风控的风险。信息完整能获取到一些前端不直接展示的元数据如文档的UUID、创建/更新时间等。因此我们的技术基石就是语雀的官方API文档。你需要做的第一件事就是去语雀的 开放平台 创建一个应用获取关键的access_token。这个Token是你所有请求的“通行证”。2.2 编程语言与工具链的考量接下来是工具的选择。Python几乎是此类自动化任务的首选原因如下生态丰富拥有requests网络请求、json数据处理、os/pathlib文件操作等成熟的内置或第三方库开箱即用。开发高效语法简洁编写爬虫和数据处理脚本速度快。跨平台在Windows、macOS、Linux上都能完美运行。除了Python你也可以使用Node.js其异步特性在处理大量IO请求时可能有优势。但对于大多数用户Python的学习曲线更平缓社区资源也更丰富。本文将基于Python进行实现。必要的Python库requests: 用于发送HTTP请求到语雀API。json: 用于解析API返回的数据。os和pathlib: 用于在本地创建目录和文件。time: 用于在请求间添加延迟遵守API速率限制避免被封。2.3 整体流程设计整个脚本的逻辑流程图如下文字描述初始化配置读取你的语雀access_token和目标知识库的namespace仓库标识。获取知识库目录调用API获取该知识库下所有文档的列表包括文档ID、标题、目录层级结构。递归遍历与下载根据目录结构递归地处理每一个文档。对于每一篇文档 a. 调用API获取文档的详细内容通常是Markdown源码。 b. 处理文档中的特殊元素如语雀独有的“画板”、“流程图”等语法这些需要转换为标准Markdown或占位符。 c. 根据文档在知识库中的路径在本地创建对应的文件夹。 d. 将处理后的Markdown内容以“标题.md”的形式保存到对应文件夹中。资源文件处理提取Markdown中的图片链接下载图片到本地如/images目录并替换文档中的链接为本地相对路径。元信息保存可选择将文档的创建时间、更新时间等元数据保存到文件头部或单独的元信息文件中。注意语雀API有调用频率限制通常每分钟不超过120次。在脚本中必须加入time.sleep()进行延时例如每次请求后暂停0.5秒这是一个安全且友好的做法。3. 实操步骤详解从零构建你的导出工具下面我将分步拆解手把手带你实现这个导出工具。请确保你的电脑已经安装了Python3。3.1 环境准备与密钥配置首先创建一个新的项目目录例如yuque_export。在该目录下我们创建两个核心文件config.json: 用于存放敏感配置信息避免将Token硬编码在脚本中。export_yuque.py: 我们的主脚本。config.json内容如下{ access_token: 你的语雀AccessToken, namespace: 你的知识库Namespace }如何获取access_token登录语雀 - 点击头像进入“设置” - 找到“Token”配置项生成一个新的Token并复制。请妥善保管它拥有读取你所有知识库的权限。如何获取namespace打开你要导出的知识库主页浏览器地址栏的路径通常是https://www.yuque.com/用户名/namespace。其中namespace就是你需要填写的部分。安装依赖库打开终端或命令提示符进入项目目录执行pip install requests3.2 核心脚本编写与解析接下来是export_yuque.py的主要内容。我会分段解释每一部分的作用。第一部分导入模块与加载配置import requests import json import os from pathlib import Path import time import re # 加载配置文件 with open(config.json, r, encodingutf-8) as f: config json.load(f) ACCESS_TOKEN config[access_token] NAMESPACE config[namespace] # API基础URL和请求头 API_BASE https://www.yuque.com/api/v2 HEADERS { User-Agent: Mozilla/5.0 (自定义导出工具), X-Auth-Token: ACCESS_TOKEN }这里我们设置了请求头其中X-Auth-Token是语雀API认证的关键。User-Agent可以自定义标识你的工具。第二部分获取知识库文档列表def get_repo_tocs(): 获取知识库的目录结构 url f{API_BASE}/repos/{NAMESPACE}/toc response requests.get(url, headersHEADERS) if response.status_code 200: return response.json()[data] else: print(f获取目录失败: {response.status_code}) print(response.text) return [] # 获取目录数据 tocs get_repo_tocs() time.sleep(0.5) # 礼貌性延迟/repos/{namespace}/toc这个API端点返回的是知识库的目录列表其中包含了每个文档的id、title、slugURL片段以及非常重要的parent_uuid用于构建树形结构。第三部分构建文档树与下载函数这是最核心的部分。我们需要将扁平的目录列表转换成树形结构然后递归地下载每个节点。def build_doc_tree(tocs): 将扁平目录列表构建为树形结构 # 首先创建一个以uuid为键的字典方便查找 node_map {item[uuid]: {**item, children: []} for item in tocs} root_nodes [] for item in tocs: node node_map[item[uuid]] parent_uuid item.get(parent_uuid) if parent_uuid and parent_uuid in node_map: # 如果存在父节点则添加到父节点的children中 node_map[parent_uuid][children].append(node) else: # 否则作为根节点 root_nodes.append(node) return root_nodes def fetch_doc_detail(doc_id): 获取单篇文档的详细信息Markdown内容 url f{API_BASE}/repos/{NAMESPACE}/docs/{doc_id} # 这里我们请求raw格式直接获取Markdown源码 params {raw: 1} response requests.get(url, headersHEADERS, paramsparams) if response.status_code 200: data response.json()[data] return data[body], data[title] else: print(f下载文档 {doc_id} 失败: {response.status_code}) return None, None def save_markdown(content, title, filepath): 将Markdown内容保存到文件 # 处理文件名移除非法字符用下划线代替 safe_title re.sub(r[\\/*?:|], _, title) filename f{safe_title}.md full_path Path(filepath) / filename # 确保目录存在 os.makedirs(filepath, exist_okTrue) with open(full_path, w, encodingutf-8) as f: f.write(content) print(f已保存: {full_path})第四部分遍历树并下载所有文档def download_doc_tree(node, base_path): 递归下载文档树 current_dir Path(base_path) / node[title] # 先创建当前文档对应的目录即使它只是文件夹也可能有同名文档 os.makedirs(current_dir, exist_okTrue) # 如果该节点有对应的文档ID则下载文档内容 if node.get(doc_id): content, title fetch_doc_detail(node[doc_id]) time.sleep(0.5) # 关键请求间延迟避免触发限流 if content and title: # 将文档保存在以它命名的文件夹内文件名为《{标题}.md》 save_markdown(content, title, current_dir) # 递归处理所有子节点 for child in node[children]: download_doc_tree(child, current_dir) # 主执行逻辑 if __name__ __main__: print(开始构建文档树...) doc_tree build_doc_tree(tocs) print(开始批量下载文档...) # 本地保存的根目录 local_base_path Path(./output) / NAMESPACE for root_node in doc_tree: download_doc_tree(root_node, local_base_path) print(导出完成)这个脚本已经具备了核心的导出功能。它会按照知识库的原有文件夹结构在本地./output/{namespace}目录下完美复刻一份。3.3 高级处理图片本地化与内容清洗基础的文本导出完成了但一个生产级的工具还需要处理资源文件。语雀文档中的图片链接是托管在语雀CDN上的为了真正的“离线化”我们需要下载这些图片。我们可以在fetch_doc_detail获取到内容后增加一个图片处理函数import os from urllib.parse import urlparse import requests def download_images_and_replace(markdown_content, doc_base_path): 下载Markdown内容中的图片并替换链接为本地路径 # 创建图片存储目录 images_dir Path(doc_base_path) / images os.makedirs(images_dir, exist_okTrue) # 正则匹配Markdown中的图片语法  pattern r!\[(.*?)\]\((https?://[^\s]?)\) def replace_match(match): alt_text match.group(1) img_url match.group(2) # 解析URL获取文件名 parsed_url urlparse(img_url) filename os.path.basename(parsed_url.path) if not filename: filename fimage_{int(time.time())}.jpg local_image_path images_dir / filename # 下载图片 try: img_response requests.get(img_url, streamTrue) if img_response.status_code 200: with open(local_image_path, wb) as f: for chunk in img_response.iter_content(1024): f.write(chunk) # 返回替换后的本地相对路径 return f except Exception as e: print(f下载图片失败 {img_url}: {e}) # 如果下载失败返回原链接 return match.group(0) # 替换所有匹配的图片链接 new_content re.sub(pattern, replace_match, markdown_content) return new_content然后在save_markdown函数中在写入文件前调用这个函数content download_images_and_replace(content, filepath)这样所有文档中的图片都会被下载到当前文档所在目录的images子文件夹中并且文档内的引用路径也会被更新为相对路径实现了完整的离线化。4. 常见问题与实战避坑指南在实际操作中你几乎一定会遇到下面这些问题。这里是我踩过坑后总结的解决方案。4.1 API限流与请求失败处理语雀API对未认证请求和认证请求都有频率限制。我们的脚本虽然加了延迟但网络波动或意外错误仍可能导致请求失败。解决方案实现重试机制。我们可以用一个包装函数来发送请求如果失败如状态码429表示请求过多或5xx服务器错误则等待一段时间后重试。def safe_request(url, headers, paramsNone, max_retries3): 带重试机制的请求函数 for i in range(max_retries): try: resp requests.get(url, headersheaders, paramsparams, timeout30) if resp.status_code 429: # Too Many Requests wait_time int(resp.headers.get(Retry-After, 60)) # 读取建议等待时间 print(f触发限流等待 {wait_time} 秒后重试...) time.sleep(wait_time) continue elif resp.status_code 500: print(f服务器错误({resp.status_code})第{i1}次重试...) time.sleep(2 ** i) # 指数退避 continue return resp # 成功则返回响应 except requests.exceptions.RequestException as e: print(f网络请求异常({e})第{i1}次重试...) time.sleep(2 ** i) # 重试多次后仍失败 print(f请求失败: {url}) return None然后在get_repo_tocs和fetch_doc_detail函数中用safe_request替换requests.get。4.2 文档标题含有非法文件名字符Windows、macOS、Linux系统对文件名都有禁止使用的字符如\,/,:,*,?,,,,|。如果文档标题包含这些字符直接用作文件名会导致保存失败。解决方案在保存前清洗文件名。我们在save_markdown函数中已经用正则表达式re.sub(r[\\/*?:|], _, title)做了处理。这是一个通用做法。对于更复杂的情况比如首尾空格、点号可以进一步处理def sanitize_filename(filename): 清洗字符串使其成为安全的文件名 # 替换系统非法字符 filename re.sub(r[\\/*?:|], _, filename) # 替换可能引起问题的空格和点开头或结尾 filename filename.strip().rstrip(.) # 去除首尾空格和末尾的点 # 限制长度可选避免超长路径错误 if len(filename) 200: filename filename[:200] # 如果清洗后文件名为空则使用一个默认名 if not filename: filename 未命名文档 return filename4.3 处理语雀特有的“卡片”、“画板”等非标语法语雀编辑器支持一些特有的语法如[[card]]、[[board]]、[[audio]]等。这些语法在标准Markdown中无法渲染。直接导出后在其他编辑器里会显示为乱码。解决方案语法转换或占位符提示。我们可以在保存内容前用正则表达式批量替换这些语法。一种保守且实用的做法是将其转换为清晰的注释或占位符提醒自己此处原有特殊内容。def convert_yuque_special_syntax(markdown_content): 转换语雀特有语法为标准Markdown或注释 # 将 [[card]]...[[/card]] 转换为提示块 content re.sub(r\[\[card\]\](.*?)\[\[/card\]\], r\n **【语雀卡片】**\n \1\n, markdown_content, flagsre.DOTALL) # 将 [[board]] 转换为提示 content re.sub(r\[\[board\]\].*?\[\[/board\]\], r\n **【语雀画板 - 请在语雀中查看】**\n, content, flagsre.DOTALL) # 处理其他已知语法... return content将清洗和转换函数按顺序应用到获取到的content上再保存就能得到更干净、兼容性更好的Markdown文件。4.4 大规模知识库导出的稳定性优化当你导出数千篇文档时脚本运行时间可能长达数小时。网络中断、程序异常都可能导致前功尽弃。解决方案实现断点续传与状态记录。我们可以引入一个简单的状态记录文件如progress.json记录已成功下载的文档ID。每次运行脚本前先加载这个记录跳过已下载的文档。PROGRESS_FILE progress.json def load_progress(): if os.path.exists(PROGRESS_FILE): with open(PROGRESS_FILE, r, encodingutf-8) as f: return set(json.load(f)) return set() def save_progress(doc_id): downloaded load_progress() downloaded.add(doc_id) with open(PROGRESS_FILE, w, encodingutf-8) as f: json.dump(list(downloaded), f) # 在 download_doc_tree 函数中下载前检查 if node.get(doc_id): if node[doc_id] in downloaded_set: # downloaded_set 是从 load_progress 加载的集合 print(f跳过已下载文档: {node[title]}) return # ... 下载逻辑 ... if content and title: save_markdown(...) save_progress(node[doc_id]) # 下载成功后记录这样即使脚本中途停止再次运行时也会从上次中断的地方继续极大地提升了导出大型知识库的可靠性。5. 导出后的整理与高效利用当你成功将所有Markdown文件导出到本地后工作只完成了一半。如何高效地管理和利用这个本地的知识库才是最终目的。5.1 文件结构与元信息增强脚本导出的文件结构保留了语雀的目录层级这很好。但你可能会发现文件缺少了创建时间、更新时间、标签等元信息。这些信息对于知识管理至关重要。我们可以修改fetch_doc_detail函数让它返回更多数据并在保存Markdown时以“Front Matter”一种在文件头部用YAML格式存储元数据的约定的形式写入文件。这是静态站点生成器如Hexo, Hugo, Jekyll和许多笔记软件如Obsidian支持的格式。def save_markdown_with_meta(content, doc_info, filepath): 保存带Front Matter元信息的Markdown文件 safe_title sanitize_filename(doc_info[title]) filename f{safe_title}.md full_path Path(filepath) / filename os.makedirs(filepath, exist_okTrue) # 构建Front Matter front_matter f--- title: {doc_info[title]} created_at: {doc_info[created_at]} updated_at: {doc_info[updated_at]} slug: {doc_info.get(slug, )} --- full_content front_matter \n content with open(full_path, w, encodingutf-8) as f: f.write(full_content) print(f已保存含元信息: {full_path})这样你的每篇Markdown文件开头都会有一个清晰的元数据块方便后续的搜索、筛选和整理。5.2 与本地笔记工具集成现在你可以将这个本地文件夹导入到你喜欢的任何工具中Obsidian直接将整个文件夹作为Vault仓库打开。Obsidian能完美识别Markdown和Front Matter其强大的双向链接、图谱视图和社区插件能让你的知识库“活”起来。VS Code配合诸如Markdown All in One,Paste Image等插件VS Code可以成为一个非常强大的Markdown编辑和预览环境。你可以使用其全局搜索功能CtrlShiftF快速定位任何内容。Typora以其“所见即所得”的流畅编辑体验著称适合专注于写作。Git这是终极的版本管理和备份方案。在本地文件夹初始化Git仓库定期提交。你不仅可以回溯历史版本还可以轻松地将知识库同步到GitHub、Gitee等远程平台实现多地备份。5.3 建立自动化备份流程数据备份贵在坚持。你可以将我们编写的Python脚本部署到一台始终开机的设备如家里的NAS、树莓派或云服务器上并使用系统的定时任务Linux的cron, Windows的任务计划程序来定期执行。例如在Linux上你可以创建一个每周日凌晨3点运行的cron任务0 3 * * 0 cd /path/to/your/yuque_export /usr/bin/python3 export_yuque.py export.log 21这样你的整个语雀知识库就会每周自动备份一次到本地并将日志输出到export.log文件中。这才是真正一劳永逸的“数据自治”。整个过程从最初的焦虑——担心数据被平台锁定到亲手写出脚本看着文档一篇篇有条不紊地下载到本地最后整合进自己得心应手的工具链里这种对个人数字资产的完全掌控感是任何云服务带来的便利都无法替代的。工具脚本本身并不复杂但其背后体现的“数据主权”意识是每一个数字时代的内容创作者都应该具备的。 
长河君 · 2026/8/12 20:22:46 · 阅读 1.2k Python自动化脚本实现语雀知识库批量导出与本地备份
1. 项目概述为什么我们需要批量导出语雀文档作为一名长期依赖语雀进行知识管理和团队协作的深度用户我几乎把所有的工作笔记、项目文档和技术沉淀都放在了上面。语雀的编辑器体验、知识库结构和协同功能确实做得不错但随着内容越积越多一个现实且紧迫的问题就浮出水面了数据安全与自主性。你可能会说语雀不是有官方的导出功能吗没错它支持单篇文档导出为Markdown、PDF等格式。但当你面对一个包含数百篇文章、结构复杂的知识库时一篇篇手动点击“导出”不仅耗时耗力更是一种精神折磨。更重要的是这种“手动”操作存在巨大风险网络波动、浏览器卡顿、甚至误操作都可能导致导出中断或遗漏。一旦你需要迁移平台、进行本地备份或者只是想用自己熟悉的工具如Obsidian、Typora、VS Code来离线编辑和检索这种低效的方式就成了拦路虎。因此“语雀批量导出MarkDown文件”这个需求本质上是一个数据资产回收与风险管理的过程。它不是为了“逃离”某个平台而是为了确保个人或团队的核心数字资产——知识——的绝对安全与可移植性。通过自动化脚本我们可以将散落在云端的结构化文档高效、完整、保真地“下载”到本地形成一个结构清晰的Markdown文件仓库。这之后无论是用Git进行版本管理用本地搜索工具进行全文检索还是进行二次加工和发布主动权都完全掌握在自己手中。2. 核心思路与技术选型解析要实现批量导出我们不能依赖图形界面必须通过程序与语雀的后台API进行交互。整个流程可以拆解为几个核心环节身份认证、文档遍历、内容获取与本地化存储。技术路线的选择直接决定了工具的稳定性、易用性和可维护性。2.1 为什么选择官方API而非模拟爬虫首先我们必须明确一个原则优先使用官方提供的合法接口。语雀为开发者提供了完善的Open API。相比于直接抓取网页Web Scraping使用API有压倒性优势稳定性高API接口稳定数据结构清晰不易因前端页面改版而失效。效率高直接获取JSON格式的纯数据无需解析复杂的HTML速度快节省带宽。合规合法在速率限制内使用是受平台支持的行为避免了因频繁爬取被风控的风险。信息完整能获取到一些前端不直接展示的元数据如文档的UUID、创建/更新时间等。因此我们的技术基石就是语雀的官方API文档。你需要做的第一件事就是去语雀的 开放平台 创建一个应用获取关键的access_token。这个Token是你所有请求的“通行证”。2.2 编程语言与工具链的考量接下来是工具的选择。Python几乎是此类自动化任务的首选原因如下生态丰富拥有requests网络请求、json数据处理、os/pathlib文件操作等成熟的内置或第三方库开箱即用。开发高效语法简洁编写爬虫和数据处理脚本速度快。跨平台在Windows、macOS、Linux上都能完美运行。除了Python你也可以使用Node.js其异步特性在处理大量IO请求时可能有优势。但对于大多数用户Python的学习曲线更平缓社区资源也更丰富。本文将基于Python进行实现。必要的Python库requests: 用于发送HTTP请求到语雀API。json: 用于解析API返回的数据。os和pathlib: 用于在本地创建目录和文件。time: 用于在请求间添加延迟遵守API速率限制避免被封。2.3 整体流程设计整个脚本的逻辑流程图如下文字描述初始化配置读取你的语雀access_token和目标知识库的namespace仓库标识。获取知识库目录调用API获取该知识库下所有文档的列表包括文档ID、标题、目录层级结构。递归遍历与下载根据目录结构递归地处理每一个文档。对于每一篇文档 a. 调用API获取文档的详细内容通常是Markdown源码。 b. 处理文档中的特殊元素如语雀独有的“画板”、“流程图”等语法这些需要转换为标准Markdown或占位符。 c. 根据文档在知识库中的路径在本地创建对应的文件夹。 d. 将处理后的Markdown内容以“标题.md”的形式保存到对应文件夹中。资源文件处理提取Markdown中的图片链接下载图片到本地如/images目录并替换文档中的链接为本地相对路径。元信息保存可选择将文档的创建时间、更新时间等元数据保存到文件头部或单独的元信息文件中。注意语雀API有调用频率限制通常每分钟不超过120次。在脚本中必须加入time.sleep()进行延时例如每次请求后暂停0.5秒这是一个安全且友好的做法。3. 实操步骤详解从零构建你的导出工具下面我将分步拆解手把手带你实现这个导出工具。请确保你的电脑已经安装了Python3。3.1 环境准备与密钥配置首先创建一个新的项目目录例如yuque_export。在该目录下我们创建两个核心文件config.json: 用于存放敏感配置信息避免将Token硬编码在脚本中。export_yuque.py: 我们的主脚本。config.json内容如下{ access_token: 你的语雀AccessToken, namespace: 你的知识库Namespace }如何获取access_token登录语雀 - 点击头像进入“设置” - 找到“Token”配置项生成一个新的Token并复制。请妥善保管它拥有读取你所有知识库的权限。如何获取namespace打开你要导出的知识库主页浏览器地址栏的路径通常是https://www.yuque.com/用户名/namespace。其中namespace就是你需要填写的部分。安装依赖库打开终端或命令提示符进入项目目录执行pip install requests3.2 核心脚本编写与解析接下来是export_yuque.py的主要内容。我会分段解释每一部分的作用。第一部分导入模块与加载配置import requests import json import os from pathlib import Path import time import re # 加载配置文件 with open(config.json, r, encodingutf-8) as f: config json.load(f) ACCESS_TOKEN config[access_token] NAMESPACE config[namespace] # API基础URL和请求头 API_BASE https://www.yuque.com/api/v2 HEADERS { User-Agent: Mozilla/5.0 (自定义导出工具), X-Auth-Token: ACCESS_TOKEN }这里我们设置了请求头其中X-Auth-Token是语雀API认证的关键。User-Agent可以自定义标识你的工具。第二部分获取知识库文档列表def get_repo_tocs(): 获取知识库的目录结构 url f{API_BASE}/repos/{NAMESPACE}/toc response requests.get(url, headersHEADERS) if response.status_code 200: return response.json()[data] else: print(f获取目录失败: {response.status_code}) print(response.text) return [] # 获取目录数据 tocs get_repo_tocs() time.sleep(0.5) # 礼貌性延迟/repos/{namespace}/toc这个API端点返回的是知识库的目录列表其中包含了每个文档的id、title、slugURL片段以及非常重要的parent_uuid用于构建树形结构。第三部分构建文档树与下载函数这是最核心的部分。我们需要将扁平的目录列表转换成树形结构然后递归地下载每个节点。def build_doc_tree(tocs): 将扁平目录列表构建为树形结构 # 首先创建一个以uuid为键的字典方便查找 node_map {item[uuid]: {**item, children: []} for item in tocs} root_nodes [] for item in tocs: node node_map[item[uuid]] parent_uuid item.get(parent_uuid) if parent_uuid and parent_uuid in node_map: # 如果存在父节点则添加到父节点的children中 node_map[parent_uuid][children].append(node) else: # 否则作为根节点 root_nodes.append(node) return root_nodes def fetch_doc_detail(doc_id): 获取单篇文档的详细信息Markdown内容 url f{API_BASE}/repos/{NAMESPACE}/docs/{doc_id} # 这里我们请求raw格式直接获取Markdown源码 params {raw: 1} response requests.get(url, headersHEADERS, paramsparams) if response.status_code 200: data response.json()[data] return data[body], data[title] else: print(f下载文档 {doc_id} 失败: {response.status_code}) return None, None def save_markdown(content, title, filepath): 将Markdown内容保存到文件 # 处理文件名移除非法字符用下划线代替 safe_title re.sub(r[\\/*?:|], _, title) filename f{safe_title}.md full_path Path(filepath) / filename # 确保目录存在 os.makedirs(filepath, exist_okTrue) with open(full_path, w, encodingutf-8) as f: f.write(content) print(f已保存: {full_path})第四部分遍历树并下载所有文档def download_doc_tree(node, base_path): 递归下载文档树 current_dir Path(base_path) / node[title] # 先创建当前文档对应的目录即使它只是文件夹也可能有同名文档 os.makedirs(current_dir, exist_okTrue) # 如果该节点有对应的文档ID则下载文档内容 if node.get(doc_id): content, title fetch_doc_detail(node[doc_id]) time.sleep(0.5) # 关键请求间延迟避免触发限流 if content and title: # 将文档保存在以它命名的文件夹内文件名为《{标题}.md》 save_markdown(content, title, current_dir) # 递归处理所有子节点 for child in node[children]: download_doc_tree(child, current_dir) # 主执行逻辑 if __name__ __main__: print(开始构建文档树...) doc_tree build_doc_tree(tocs) print(开始批量下载文档...) # 本地保存的根目录 local_base_path Path(./output) / NAMESPACE for root_node in doc_tree: download_doc_tree(root_node, local_base_path) print(导出完成)这个脚本已经具备了核心的导出功能。它会按照知识库的原有文件夹结构在本地./output/{namespace}目录下完美复刻一份。3.3 高级处理图片本地化与内容清洗基础的文本导出完成了但一个生产级的工具还需要处理资源文件。语雀文档中的图片链接是托管在语雀CDN上的为了真正的“离线化”我们需要下载这些图片。我们可以在fetch_doc_detail获取到内容后增加一个图片处理函数import os from urllib.parse import urlparse import requests def download_images_and_replace(markdown_content, doc_base_path): 下载Markdown内容中的图片并替换链接为本地路径 # 创建图片存储目录 images_dir Path(doc_base_path) / images os.makedirs(images_dir, exist_okTrue) # 正则匹配Markdown中的图片语法  pattern r!\[(.*?)\]\((https?://[^\s]?)\) def replace_match(match): alt_text match.group(1) img_url match.group(2) # 解析URL获取文件名 parsed_url urlparse(img_url) filename os.path.basename(parsed_url.path) if not filename: filename fimage_{int(time.time())}.jpg local_image_path images_dir / filename # 下载图片 try: img_response requests.get(img_url, streamTrue) if img_response.status_code 200: with open(local_image_path, wb) as f: for chunk in img_response.iter_content(1024): f.write(chunk) # 返回替换后的本地相对路径 return f except Exception as e: print(f下载图片失败 {img_url}: {e}) # 如果下载失败返回原链接 return match.group(0) # 替换所有匹配的图片链接 new_content re.sub(pattern, replace_match, markdown_content) return new_content然后在save_markdown函数中在写入文件前调用这个函数content download_images_and_replace(content, filepath)这样所有文档中的图片都会被下载到当前文档所在目录的images子文件夹中并且文档内的引用路径也会被更新为相对路径实现了完整的离线化。4. 常见问题与实战避坑指南在实际操作中你几乎一定会遇到下面这些问题。这里是我踩过坑后总结的解决方案。4.1 API限流与请求失败处理语雀API对未认证请求和认证请求都有频率限制。我们的脚本虽然加了延迟但网络波动或意外错误仍可能导致请求失败。解决方案实现重试机制。我们可以用一个包装函数来发送请求如果失败如状态码429表示请求过多或5xx服务器错误则等待一段时间后重试。def safe_request(url, headers, paramsNone, max_retries3): 带重试机制的请求函数 for i in range(max_retries): try: resp requests.get(url, headersheaders, paramsparams, timeout30) if resp.status_code 429: # Too Many Requests wait_time int(resp.headers.get(Retry-After, 60)) # 读取建议等待时间 print(f触发限流等待 {wait_time} 秒后重试...) time.sleep(wait_time) continue elif resp.status_code 500: print(f服务器错误({resp.status_code})第{i1}次重试...) time.sleep(2 ** i) # 指数退避 continue return resp # 成功则返回响应 except requests.exceptions.RequestException as e: print(f网络请求异常({e})第{i1}次重试...) time.sleep(2 ** i) # 重试多次后仍失败 print(f请求失败: {url}) return None然后在get_repo_tocs和fetch_doc_detail函数中用safe_request替换requests.get。4.2 文档标题含有非法文件名字符Windows、macOS、Linux系统对文件名都有禁止使用的字符如\,/,:,*,?,,,,|。如果文档标题包含这些字符直接用作文件名会导致保存失败。解决方案在保存前清洗文件名。我们在save_markdown函数中已经用正则表达式re.sub(r[\\/*?:|], _, title)做了处理。这是一个通用做法。对于更复杂的情况比如首尾空格、点号可以进一步处理def sanitize_filename(filename): 清洗字符串使其成为安全的文件名 # 替换系统非法字符 filename re.sub(r[\\/*?:|], _, filename) # 替换可能引起问题的空格和点开头或结尾 filename filename.strip().rstrip(.) # 去除首尾空格和末尾的点 # 限制长度可选避免超长路径错误 if len(filename) 200: filename filename[:200] # 如果清洗后文件名为空则使用一个默认名 if not filename: filename 未命名文档 return filename4.3 处理语雀特有的“卡片”、“画板”等非标语法语雀编辑器支持一些特有的语法如[[card]]、[[board]]、[[audio]]等。这些语法在标准Markdown中无法渲染。直接导出后在其他编辑器里会显示为乱码。解决方案语法转换或占位符提示。我们可以在保存内容前用正则表达式批量替换这些语法。一种保守且实用的做法是将其转换为清晰的注释或占位符提醒自己此处原有特殊内容。def convert_yuque_special_syntax(markdown_content): 转换语雀特有语法为标准Markdown或注释 # 将 [[card]]...[[/card]] 转换为提示块 content re.sub(r\[\[card\]\](.*?)\[\[/card\]\], r\n **【语雀卡片】**\n \1\n, markdown_content, flagsre.DOTALL) # 将 [[board]] 转换为提示 content re.sub(r\[\[board\]\].*?\[\[/board\]\], r\n **【语雀画板 - 请在语雀中查看】**\n, content, flagsre.DOTALL) # 处理其他已知语法... return content将清洗和转换函数按顺序应用到获取到的content上再保存就能得到更干净、兼容性更好的Markdown文件。4.4 大规模知识库导出的稳定性优化当你导出数千篇文档时脚本运行时间可能长达数小时。网络中断、程序异常都可能导致前功尽弃。解决方案实现断点续传与状态记录。我们可以引入一个简单的状态记录文件如progress.json记录已成功下载的文档ID。每次运行脚本前先加载这个记录跳过已下载的文档。PROGRESS_FILE progress.json def load_progress(): if os.path.exists(PROGRESS_FILE): with open(PROGRESS_FILE, r, encodingutf-8) as f: return set(json.load(f)) return set() def save_progress(doc_id): downloaded load_progress() downloaded.add(doc_id) with open(PROGRESS_FILE, w, encodingutf-8) as f: json.dump(list(downloaded), f) # 在 download_doc_tree 函数中下载前检查 if node.get(doc_id): if node[doc_id] in downloaded_set: # downloaded_set 是从 load_progress 加载的集合 print(f跳过已下载文档: {node[title]}) return # ... 下载逻辑 ... if content and title: save_markdown(...) save_progress(node[doc_id]) # 下载成功后记录这样即使脚本中途停止再次运行时也会从上次中断的地方继续极大地提升了导出大型知识库的可靠性。5. 导出后的整理与高效利用当你成功将所有Markdown文件导出到本地后工作只完成了一半。如何高效地管理和利用这个本地的知识库才是最终目的。5.1 文件结构与元信息增强脚本导出的文件结构保留了语雀的目录层级这很好。但你可能会发现文件缺少了创建时间、更新时间、标签等元信息。这些信息对于知识管理至关重要。我们可以修改fetch_doc_detail函数让它返回更多数据并在保存Markdown时以“Front Matter”一种在文件头部用YAML格式存储元数据的约定的形式写入文件。这是静态站点生成器如Hexo, Hugo, Jekyll和许多笔记软件如Obsidian支持的格式。def save_markdown_with_meta(content, doc_info, filepath): 保存带Front Matter元信息的Markdown文件 safe_title sanitize_filename(doc_info[title]) filename f{safe_title}.md full_path Path(filepath) / filename os.makedirs(filepath, exist_okTrue) # 构建Front Matter front_matter f--- title: {doc_info[title]} created_at: {doc_info[created_at]} updated_at: {doc_info[updated_at]} slug: {doc_info.get(slug, )} --- full_content front_matter \n content with open(full_path, w, encodingutf-8) as f: f.write(full_content) print(f已保存含元信息: {full_path})这样你的每篇Markdown文件开头都会有一个清晰的元数据块方便后续的搜索、筛选和整理。5.2 与本地笔记工具集成现在你可以将这个本地文件夹导入到你喜欢的任何工具中Obsidian直接将整个文件夹作为Vault仓库打开。Obsidian能完美识别Markdown和Front Matter其强大的双向链接、图谱视图和社区插件能让你的知识库“活”起来。VS Code配合诸如Markdown All in One,Paste Image等插件VS Code可以成为一个非常强大的Markdown编辑和预览环境。你可以使用其全局搜索功能CtrlShiftF快速定位任何内容。Typora以其“所见即所得”的流畅编辑体验著称适合专注于写作。Git这是终极的版本管理和备份方案。在本地文件夹初始化Git仓库定期提交。你不仅可以回溯历史版本还可以轻松地将知识库同步到GitHub、Gitee等远程平台实现多地备份。5.3 建立自动化备份流程数据备份贵在坚持。你可以将我们编写的Python脚本部署到一台始终开机的设备如家里的NAS、树莓派或云服务器上并使用系统的定时任务Linux的cron, Windows的任务计划程序来定期执行。例如在Linux上你可以创建一个每周日凌晨3点运行的cron任务0 3 * * 0 cd /path/to/your/yuque_export /usr/bin/python3 export_yuque.py export.log 21这样你的整个语雀知识库就会每周自动备份一次到本地并将日志输出到export.log文件中。这才是真正一劳永逸的“数据自治”。整个过程从最初的焦虑——担心数据被平台锁定到亲手写出脚本看着文档一篇篇有条不紊地下载到本地最后整合进自己得心应手的工具链里这种对个人数字资产的完全掌控感是任何云服务带来的便利都无法替代的。工具脚本本身并不复杂但其背后体现的“数据主权”意识是每一个数字时代的内容创作者都应该具备的。