企业官网建设流程全解析

飞书文档批量导出只用三步：一条命令同步整个知识库，彻底告别手动下载

【免费下载链接】feishu-doc-export飞书文档导出服务项目地址: https://gitcode.com/gh_mirrors/fe/feishu-doc-export

周一早会刚结束，领导丢来一句话：公司要从飞书切回企业微信，知识库里 700 多篇文档，一周内全部迁走。你打开飞书，看着文档列表陷入沉思——一篇篇点开、下载、保存，按每篇 2 分钟算，100 篇就要 3 个多小时，还得时刻担心目录结构乱掉、格式丢光。如果你也被这种场面困住过，那这篇要讲的 feishu-doc-export 飞书文档批量导出工具，正好能把 700 篇的活儿压到 25 分钟，而且是后台挂着跑，不影响你干别的。

30 秒速览：它到底能做什么

feishu-doc-export 是一个基于 .NET Core 开发的飞书文档导出服务，支持 Windows、Mac、Linux 三种系统，一条命令就能把整个知识库（或个人空间某个文件夹）的文档同步到本地，输出 docx、markdown、pdf 三种格式，目录结构保持和飞书原样一致。

第一步：拿到飞书 API 凭证

动手前先准备两个"钥匙"：App ID 和 App Secret。去飞书开发者后台创建一个企业自建应用，信息随便填，重点是开权限。在权限管理里开通云文档相关的查看、导出权限，比如"查看、评论和下载云空间中所有文件""导出云文档""查看、编辑和管理知识库"这几项，再给应用加上机器人能力，发布一个版本等待管理员审核通过。

然后回到凭证与基础信息页面，App ID 和 App Secret 就在这里，先复制保存好。

小提示：如果只想本地测试，可以创建测试企业并绑定应用，切到测试版本，再建一个测试知识库来练手，不会影响正式环境。

凭证到手后，接下来就是关键一步——把工具下载下来。

第二步：下载程序并授权

克隆源码或用 Release 版本都行：

# 克隆项目源码 git clone https://gitcode.com/gh_mirrors/fe/feishu-doc-export

按系统选择压缩包：Windows 用feishu-doc-export-win-x64.zip，Mac 用mac-osx-x64，Linux 用linux-x64。解压后，Windows 的可执行文件是feishu-doc-export.exe，Mac 和 Linux 是没后缀的feishu-doc-export。

Mac 和 Linux 用户注意，首次使用要先把文件变成可执行：

# 把文件授权为可执行文件 sudo chmod +x ./feishu-doc-export

执行时建议加sudo，否则可能因为权限不足，连保存文档的目录都建不出来——这个坑很多人踩过。

第三步：执行导出命令

程序下载好了，最后一步就是运行。最简单的导出命令只有三个必填参数：

# Windows 示例 ./feishu-doc-export.exe --appId=你的AppId --appSecret=你的AppSecret --exportPath=E:\文档备份 # Mac / Linux 示例 sudo ./feishu-doc-export --appId=你的AppId --appSecret=你的AppSecret --exportPath=/home/文档备份

不传--spaceId时，程序会列出你有权限的所有知识库，让你输入序号选择，适合不确定知识库 ID 的情况；指定了就直接导，适合写进脚本做自动化。常用参数再记一份：

比如导出个人空间的某个文件夹并转成 Markdown，命令长这样：

# Windows 导出个人空间文档为 Markdown ./feishu-doc-export.exe --appId=xxx --appSecret=xxx --saveType=md --exportPath=E:\temp\test --type=cloudDoc --folderToken=xxx

手动 vs 工具：差距到底在哪

手动下载慢不只是操作多，更坑的是过程不可控。网络一抖、电脑一卡，下载到一半的进度说没就没。而 feishu-doc-export 的思路完全不同：程序逐篇创建飞书导出任务、轮询结果、下载落盘，单篇失败会记录日志并跳过，其余文档照常继续，所以 700 多篇跑 25 分钟，跑完还能给你列一张"哪些没导成功"的清单，方便你单独补。

至于内部实现，看懂大概结构就行：飞书接口的调用封装在src/feishu-doc-export/HttpApi/，格式转换和文件处理在src/feishu-doc-export/Helper/，主流程在Program.cs，文档路径映射交给DocumentPathGenerator.cs和CloudDocPathGenerator.cs处理——想二次开发可以从这几个目录下手。

实战场景一：企业知识库整体迁移

最典型的用法就是开头的场景。拿企业自己的 App 凭证，指定知识库 ID，一步到位：

# 导出整个知识库为 docx，保存到本地备份目录 ./feishu-doc-export --appId=企业AppId --appSecret=企业AppSecret --spaceId=知识库ID --exportPath=/企业文档备份

命令跑起来之后，你可以正常去开会、写代码，程序在后台安静地干活，跑完看一眼日志清单就行。

实战场景二：定期备份 + 纳入版本管理

需要定期备份的团队，可以把这个命令塞进 cron 定时任务，每个月自动生成一份备份目录：

#!/bin/bash # 创建月度备份目录 BACKUP_DIR="/backup/feishu/$(date +%Y-%m)" mkdir -p $BACKUP_DIR # 执行批量导出，保存为 markdown ./feishu-doc-export --appId=$APP_ID --appSecret=$APP_SECRET --exportPath=$BACKUP_DIR --saveType=md

技术团队还可以把导出的 Markdown 直接丢进 Git 仓库，文档变更一目了然：

# 导出到项目 docs 目录 ./feishu-doc-export --appId=$APP_ID --appSecret=$APP_SECRET --saveType=md --exportPath=./docs # 提交到版本控制 git add . && git commit -m "docs: 更新飞书文档备份 $(date +%Y-%m-%d)" && git push

避坑指南：这几个坑提前帮你踩过

Q1：导出时报权限错误怎么办？多半是应用权限没开全或机器人没进知识库。核对三点：权限管理里该开的文档权限是否都开了、应用版本是否已发布上线、机器人是否被添加到了知识库的管理员群组。

Q2：知识库 ID 和文件夹 Token 去哪找？知识库 ID 看飞书知识库的 URL，space/后面的那串字符串就是。个人空间文件夹 Token 更简单：右键文件夹"获取链接"，folderToken=后面的值就是。

Q3：Markdown 导出有格式丢失？这是已知限制。工具是先调飞书接口下载 docx，再用 Aspose.Words 转成 Markdown，所以引用语法、表格、行内代码块这类格式可能丢。追求完美排版就用 docx 或 pdf，Markdown 更适合当纯文本备份。

Q4：文件名太长导不出来？系统对文件名长度有限制，超长的文档会被自动跳过并记进日志清单。遇到这种情况，改短飞书里的文档名再单独补导即可。

现在就可以动手

回到开头那个 700 篇的迁移任务：创建应用、开通权限、下载程序、跑一条命令，25 分钟后本地就多了一份和飞书结构一致的完整备份。与其花一下午点鼠标，不如花 10 分钟把飞书文档批量导出跑起来。现在就可以去开发者后台创建你的应用，完成飞书文档导出工具的第一步配置，让文档迁移这件事，从此只花一杯咖啡的时间。

【免费下载链接】feishu-doc-export飞书文档导出服务项目地址: https://gitcode.com/gh_mirrors/fe/feishu-doc-export