一次真实的迁移手记：如何用一个命令完成飞书文档批量导出

一次真实的迁移手记如何用一个命令完成飞书文档批量导出【免费下载链接】feishu-doc-export飞书文档导出服务项目地址: https://gitcode.com/gh_mirrors/fe/feishu-doc-export周五下午四点半领导走过来拍了拍我的肩膀下周要把咱们知识库整体迁到新平台七百多个文档你安排一下。我盯着飞书里密密麻麻的目录树心里已经开始计算手动下载的时间成本——每个文档打开、导出、重命名、分类平均两分钟七百个就是二十多个小时。就在我准备接受这个体力活时同事推给我一个开源项目 feishu-doc-export一个基于 .NET Core 的命令行小工具号称一行命令就能完成飞书文档批量导出还能保留原始目录结构。半信半疑之下我花了不到半小时把它跑通最终这七百多个文档在 25 分钟内全部落到了本地。它是什么不是什么feishu-doc-export 不是网页服务也不需要你开着浏览器挂着在线工具。它是一个在你电脑上运行的命令行程序给它几个参数它自己去调用飞书开放平台的 API把文档一篇篇拉回本地。你可以把它理解成一个搬运工——告诉它源地址和目标地址剩下的事情它自己完成。同时也要说清楚它不是什么它不是无损格式转换器Markdown 导出会丢失部分排版它也不是图形化客户端全程靠终端交互。弄清楚边界用起来才不会失望。几个关键亮点一句话一个一行命令导出整个知识库文档、表格甚至附件文件都能带走本地目录结构与飞书原目录一一对应迁移后不用重新整理支持 docx / md / pdf 三种格式按需切换Windows、macOS、Linux 通用导出过程在后台运行不耽误干活三个参数跑通第一次导出整个上手过程可以浓缩成三步每一步都不需要写代码。第一步拿凭证。在飞书开发者后台创建一个企业自建应用在权限管理里开通云文档相关的查看、下载、导出权限注意权限列表有分页别漏页给应用加上机器人能力然后创建版本并发布上线。接着在凭证与基础信息页面复制 App ID 和 App Secret。这一步是整套流程里最磨人的但只需做一次。第二步拿程序。从项目仓库的 Releases 页面按你的系统下载对应压缩包解压即用Windows 下可执行文件是feishu-doc-export.exemacOS 和 Linux 下是feishu-doc-export无后缀。第三步跑命令。把三个占位符替换成自己的真实值即可./feishu-doc-export --appId你的AppId --appSecret你的AppSecret --exportPath/data/backup/feishu如果不知道知识库 ID也可以不传--spaceId程序会列出当前应用有权限访问的所有知识库让你输入序号选择。命令跑起来后终端会一行行打印正在导出文档——第 N 个你大可以去冲杯咖啡回来时文档已经整整齐齐躺在目标目录里了。两个小提醒macOS 和 Linux 第一次使用要先执行sudo chmod x ./feishu-doc-export授权可执行运行时也建议加sudo否则可能因目录权限不足保存失败。我实际跑过的一次导出说说我第一次跑时踩的坑希望能帮你省下排查时间。第一次执行程序秒退报错没有找到参数。原因很简单——我在终端里复制命令时把参数之间的换行也带了进去整理成单行后就好了。第二次执行程序能跑却提示没有可支持导出的知识库。排查后发现应用虽然发布上线了但管理员还没把机器人加进知识库的成员列表。在飞书客户端里把机器人所在群组设为知识库管理员后问题立刻消失。这一步很关键权限配了、应用发布了不代表机器人自动拥有知识库访问权。第三次执行终于顺利。七百多个文档的导出过程中个别文档因为文件名超长或格式特殊被程序自动跳过结束时统一列出清单方便手动补下载。最终所有文档落盘本地目录结构与飞书里完全一致嵌套文件夹、子页面层级都没乱。那次之后我又在 Mac 上试了一次遇到了无法验证开发者的系统拦截需要在隐私与安全性里手动允许运行——这是 macOS 的常规操作不是程序的 bug。把这套工具玩出花基础导出跑通后可以试试几个进阶玩法。按格式切换。--saveType支持docx、md、pdf三种取值。实测 docx 最快md 与 docx 速度接近pdf 最慢图片要内嵌。做归档备份选 docx做内容检索选 md做对外分享选 pdf。按空间分批。知识库多的时候别一口气全导给每个空间单独指定--spaceId分批执行互不干扰也方便分目录存放./feishu-doc-export --appIdxxx --appSecretxxx --spaceId主空间ID --exportPath/backup/main ./feishu-doc-export --appIdxxx --appSecretxxx --spaceId子空间ID --exportPath/backup/sub导出个人空间云文档。加--typecloudDoc和--folderToken两个参数就能把个人空间某个文件夹下的文档也拉下来。folderToken 可以通过分享该文件夹、复制链接获取。纳入版本管理。把导出的 md 文件放进 Git 仓库再配合 cron 或计划任务定期重跑就形成了一套轻量的文档自动备份与变更记录体系团队 wiki 的历史版本一目了然。兼容 Lark。如果团队用的是飞书国际版 Lark通过--apiEndpoint指定对应的 API 地址即可工具同样适用。什么时候适合用它什么时候别用适合的场景知识库整体迁移或全量备份文档数量以百计、以千计需要保留原始目录结构且希望本地文件可搜索、可进版本库想在 Windows / Mac / Linux 上统一一套备份脚本不适合的场景只导出零星几篇文档——手动下载反而更快对 Markdown 排版有极致要求——md 经由 docx 中转转换引用、表格、行内代码等格式会丢失需要完美还原时优先选 docx 或 pdf个人空间文档需要按文件夹列表挑选——受飞书个人空间登录限制工具只支持指定文件夹导出不支持列目录选择三个新手常踩的坑权限没开全应用权限要在权限管理里逐项勾选并发布新版本缺一项就可能导出失败忘了 chmodmacOS / Linux 直接运行会提示无权限先执行sudo chmod x文件名超长超过系统命名限制的文档会被自动跳过结束时会列出清单记得手动补结语七百多个文档、25 分钟、一条命令、目录结构原样保留——这就是 feishu-doc-export 给我最直接的印象。它不复杂也没有花哨的界面但恰恰解决了我当时最痛的问题把时间从机械的重复劳动里省出来。如果你也在为飞书文档批量导出、知识库批量备份或飞书文档迁移发愁不妨用git clone https://gitcode.com/gh_mirrors/fe/feishu-doc-export拉下仓库直接下载一个 Release 版本试试。想深入了解实现可以翻翻核心源码 src/feishu-doc-export/API 调用封装在 src/feishu-doc-export/HttpApi/目录映射与格式转换分别在 DocumentPathGenerator.cs 和 src/feishu-doc-export/Helper/。希望这个工具也能帮你省下一个周末。【免费下载链接】feishu-doc-export飞书文档导出服务项目地址: https://gitcode.com/gh_mirrors/fe/feishu-doc-export创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考