feishu-cli 从零搭建指南：MD 自动发布到飞书在线文档

目标：在一台完全没碰过 feishu-cli 的电脑上，实现将本地 Markdown 文件自动发布为飞书在线文档，并转移文档所有权给开发者本人。

适用系统：Windows 10/11

预计耗时：30~40 分钟（首次搭建）

---

全局流程概览

flowchart TD
    A[1. 安装 feishu-cli] --> B[2. 创建飞书应用]
    B --> C[3. 配置应用权限]
    C --> D[4. 配置重定向 URL]
    D --> E[5. 发布应用]
    E --> F[6. 创建 config.yaml]
    F --> G[7. OAuth 登录认证]
    G --> H[8. 导入 MD 到飞书]
    H --> I[9. 转移文档所有权]
    I --> J(完成)

    style A fill:#4CAF50,color:#fff
    style J fill:#2196F3,color:#fff

---

第一步：安装 feishu-cli

1.1 下载

前往 GitHub Releases 页面下载 Windows 版本：

下载地址：https://github.com/riba2534/feishu-cli/releases

找到最新版本，下载文件名包含 windows-amd64 的压缩包，例如：

feishu-cli_vX.X.X_windows-amd64.tar.gz

1.2 解压

将压缩包解压到一个固定目录，建议：

E:\tools\feishu-cli\

解压后会得到一个 feishu-cli.exe 文件。

1.3 添加到系统 PATH（推荐）

这样可以在任意目录下使用 feishu-cli 命令：

1. 按 Win + S 搜索 "编辑系统环境变量"，打开
2. 点击 "环境变量" 按钮
3. 在 "系统变量" 或 "用户变量" 中找到 Path，双击编辑
4. 点击 "新建"，填入 feishu-cli.exe 所在目录，例如 E:\tools\feishu-cli
5. 一路确定保存

1.4 验证安装

打开新的 CMD 或 PowerShell 窗口，执行：

feishu-cli --version

看到版本号输出即安装成功 ✅

---

第二步：创建飞书自建应用

这一步在飞书开放平台网页上操作，不需要写代码。

2.1 进入开放平台

打开浏览器访问：https://open.feishu.cn/app

使用你的飞书账号登录。

2.2 创建应用

1. 点击 "创建应用" → 选择 "企业自建应用"
2. 填写应用信息：
   • 应用名称：随意起，如 MD发布工具 或 feishu-cli
   • 应用描述：Markdown 文档自动发布工具
   • 图标：随意上传一个
3. 点击 "创建"

2.3 记录关键凭证

创建完成后，在 "凭证与基础信息" 页面找到：

凭证	说明	示例
App ID	应用唯一标识，以 cli_ 开头	cli_a930a2491a7b1bc6
App Secret	应用密钥	2p9ZjGVZbC480vCx...

⚠️ App Secret 很重要，不要泄露！ 后面配置文件要用到这两个值。

---

第三步：配置应用权限

这一步决定了 feishu-cli 能调用哪些飞书 API，必须逐项开启。

3.1 进入权限管理

在应用管理页面，左侧菜单找到 "权限管理"。

3.2 搜索并开通以下权限

在权限搜索框中逐个搜索以下权限，点击 "开通"：

📄 文档相关（核心）

权限名称	权限说明
docx:document	查看、评论、编辑和管理多维表格
docx:document:readonly	获取文档内容
drive:drive	查看、评论、编辑和管理云空间中所有文件
drive:drive:readonly	查看云空间中的文件
drive:file:download	下载云空间中的文件

🔐 权限管理相关

权限名称	权限说明
docs:permission.member:create	添加协作者
docs:permission.member:readonly	查看协作者列表
docs:permission.member:delete	删除协作者
docs:permission.setting:write	更新公开权限

🖼️ 素材与画板相关

权限名称	权限说明
drive:drive:upload	上传云空间中的文件
board:board	查看和管理画板

👤 用户身份相关（用于 OAuth 登录）

权限名称	权限说明
contact:user.base:readonly	获取用户基本信息
auth:user.id:read	获取用户身份信息

🔍 搜索相关（可选）

权限名称	权限说明
search:docs:read	搜索云文档
search:message	搜索消息

📝 知识库相关（可选）

权限名称	权限说明
wiki:wiki:readonly	查看知识库
wiki:wiki	管理知识库

💡 小技巧：权限搜索时用英文关键词搜索更快，比如搜 docx、drive、permission 等。

3.3 确认权限已开通

开通后，权限列表中对应的权限状态应该显示为 "已开通"。

---

第四步：配置重定向 URL（OAuth 登录用）

4.1 进入安全设置

在应用管理页面，左侧菜单找到 "安全设置"。

4.2 添加重定向 URL

在 "重定向 URL" 一栏，添加：

http://127.0.0.1:9768/callback

点击 "保存"。

⚠️ 这一步必须做！ 否则后面 OAuth 登录时浏览器回调会失败。

---

第五步：发布应用

应用创建后是 "未发布" 状态，所有 API 调用都会被拒绝。必须发布后才能使用。

5.1 创建版本

1. 在应用管理页面，左侧菜单找到 "版本管理与发布"
2. 点击 "创建版本"
3. 填写：
   • 版本号：1.0.0
   • 更新说明：初始版本
4. 点击 "保存" → "提交审核"

5.2 审核通过

• 如果你是企业管理员，可以直接在 "审核管理" 中自行审批通过
• 如果不是管理员，需要联系管理员审批

5.3 确认发布状态

审核通过后，应用状态变为 "已发布" ✅

💡 自建应用一般秒过审，不用等太久。

---

第六步：创建配置文件

6.1 创建配置目录

feishu-cli 的配置文件存放在用户主目录下。在终端执行：

mkdir -p ~/.feishu-cli

6.2 创建 config.yaml

在 ~/.feishu-cli/ 目录下创建 config.yaml 文件：

Windows 系统中 ~ 对应 C:\Users\你的用户名，完整路径即 C:\Users\你的用户名\.feishu-cli\config.yaml

# 飞书 CLI 配置文件
# 将下面的 app_id 和 app_secret 替换成你在第二步中记录的凭证

app_id: "cli_你的AppID"
app_secret: "你的AppSecret"
base_url: "https://open.feishu.cn"
debug: false

# 导出配置
export:
  download_images: true
  assets_dir: "./assets"

# 导入配置
import:
  upload_images: true

⚠️ 关键：把 cli_你的AppID 和 你的AppSecret 替换成第二步记录的真实值！

6.3 验证配置

执行以下命令确认配置生效：

feishu-cli auth status

如果返回 {"logged_in": false}，说明配置文件已生效（只是还没登录）✅

---

第七步：OAuth 登录认证

这一步用你的飞书个人账号进行 OAuth 授权，让 feishu-cli 获得用户身份（用于搜索、权限转移等操作）。

7.1 执行登录命令

feishu-cli auth login --scopes "offline_access"

offline_access 非常重要！没有它，Token 2 小时就过期了；有它，Refresh Token 能用 30 天。

7.2 浏览器授权

命令执行后会自动打开浏览器，跳转到飞书授权页面：

1. 点击 "同意授权"
2. 浏览器会跳转到一个 127.0.0.1:9768/callback?code=xxx&state=yyy 的页面
3. 页面可能显示 "无法访问此网站" —— 这是正常的！
4. feishu-cli 会自动捕获回调并完成认证

7.3 确认登录成功

feishu-cli auth status

返回类似以下内容即成功 ✅：

{
  "logged_in": true,
  "access_token_valid": true,
  "refresh_token_valid": true,
  "scope": "auth:user.id:read offline_access"
}

7.4 （备选）两步式非交互登录

如果上面的自动方式不行（比如端口冲突、没有浏览器等），可以用两步式：

# 步骤 1：生成授权 URL
feishu-cli auth login --print-url --scopes "offline_access"

会输出一个 JSON，里面有 auth_url。把这个 URL 复制到浏览器打开，完成授权后，浏览器地址栏会变成：

http://127.0.0.1:9768/callback?code=XXXXX&state=YYYYY

复制这个完整 URL，然后执行：

# 步骤 2：用回调 URL 换 Token
feishu-cli auth callback "http://127.0.0.1:9768/callback?code=XXXXX&state=YYYYY" --state "YYYYY"

注意 --state 的值要和输出 JSON 里的 state 字段一致！

---

第八步：导入 MD 文件到飞书

8.1 准备 MD 文件

确保你的 Markdown 文件使用 UTF-8 编码，放在任意目录下即可。

8.2 执行导入

feishu-cli doc import "C:\Users\你的用户名\Desktop\技术方案.md" --title "技术方案"

参数说明：

参数	说明
C:\...\技术方案.md	Markdown 文件的完整路径
--title "技术方案"	飞书文档的标题（可选，默认用文件名）
--upload-images	自动上传本地和网络图片到飞书（可选，推荐加）

加上图片上传的完整命令：

feishu-cli doc import "C:\Users\你的用户名\Desktop\技术方案.md" --title "技术方案" --upload-images

8.3 记录文档 ID

导入成功后会输出：

已导入文档！
  文档 ID: VWYodX6kqoGNeIxOKOCc2Xvjnxg
  文档链接: https://feishu.cn/docx/VWYodX6kqoGNeIxOKOCc2Xvjnxg
  导入块数: 25

把文档 ID 记下来（就是 VWYodX6kqoGNeIxOKOCc2Xvjnxg 这串），下一步要用！

---

第九步：转移文档所有权

⚠️ 为什么需要这一步？ 因为通过 API 创建的文档，所有者是飞书应用（机器人），不是你本人。你直接打开文档链接会提示"无权限"。必须把所有权转移给自己。

9.1 添加权限

先给自己的账号添加完全访问权限（用你的飞书注册邮箱）：

feishu-cli perm add VWYodX6kqoGNeIxOKOCc2Xvjnxg \
  --doc-type docx \
  --member-type email \
  --member-id "你的飞书邮箱@公司域名.com" \
  --perm full_access \
  --notification

9.2 转移所有权

feishu-cli perm transfer-owner VWYodX6kqoGNeIxOKOCc2Xvjnxg \
  --doc-type docx \
  --member-type email \
  --member-id "你的飞书邮箱@公司域名.com" \
  --notification

成功输出：

文档所有权转移成功！
  文档: VWYodX6kqoGNeIxOKOCc2Xvjnxg
  新所有者: 你的飞书邮箱@公司域名.com（email）
  原所有者保留权限: full_access

9.3 验证

打开文档链接 https://feishu.cn/docx/VWYodX6kqoGNeIxOKOCc2Xvjnxg，确认能正常编辑 ✅

---

🎯 一键脚本（日常使用）

把上面的第八步和第九步封装成一个脚本，以后一键发布：

#!/bin/bash
# feishu-publish.sh - 一键发布 MD 到飞书文档
# 用法: ./feishu-publish.sh <md文件路径> <文档标题> <你的飞书邮箱>

MD_FILE="$1"
TITLE="$2"
EMAIL="$3"

if [ -z "$MD_FILE" ] || [ -z "$TITLE" ] || [ -z "$EMAIL" ]; then
  echo "用法: ./feishu-publish.sh <md文件路径> <文档标题> <你的飞书邮箱>"
  exit 1
fi

echo "📄 正在导入: $MD_FILE"

# 导入 MD 到飞书
RESULT=$(feishu-cli doc import "$MD_FILE" --title "$TITLE" --upload-images 2>&1)
echo "$RESULT"

# 提取文档 ID
DOC_ID=$(echo "$RESULT" | grep -oP '文档 ID: \K[A-Za-z0-9]+' || echo "$RESULT" | grep -oE '[A-Za-z0-9]{20,}' | head -1)

if [ -z "$DOC_ID" ]; then
  echo "❌ 导入失败，无法获取文档 ID"
  exit 1
fi

echo "📝 文档 ID: $DOC_ID"

# 添加完全访问权限
echo "🔐 正在添加权限..."
feishu-cli perm add "$DOC_ID" \
  --doc-type docx \
  --member-type email \
  --member-id "$EMAIL" \
  --perm full_access \
  --notification

# 转移所有权
echo "🔄 正在转移所有权..."
feishu-cli perm transfer-owner "$DOC_ID" \
  --doc-type docx \
  --member-type email \
  --member-id "$EMAIL" \
  --notification

echo ""
echo "✅ 发布完成！"
echo "📎 文档链接: https://feishu.cn/docx/$DOC_ID"

使用方法：

chmod +x feishu-publish.sh
./feishu-publish.sh "C:/Users/msn/Desktop/技术方案.md" "技术方案" "wangkunlun@poolking-tech.com"

---

支持的 Markdown 特性

以下 MD 语法都能正确导入飞书文档：

语法	说明	示例
标题	# ~ ######	# 一级标题
段落/文本	普通文本	直接写
粗体	**文本**	粗体
斜体	*文本*	斜体
删除线	~~文本~~	删除线
行内代码	`代码`	code
链接	[文字](URL)	链接
无序列表	- 项目	嵌套用缩进
有序列表	1. 项目	支持嵌套
任务列表	- [ ] / - [x]	待办/已完成
代码块	```语言	带语法高亮
Mermaid 图表	自动转飞书画板	流程图/时序图/ER图等
PlantUML 图表	自动转飞书画板	活动图/类图等
表格	`	表头
图片		自动上传
公式	$公式$ / $$公式$$	LaTeX 语法
引用	> 文本	支持嵌套
Callout	> [!NOTE]	6 种类型
分割线	---	水平线
下划线	<u>文本</u>	HTML 语法

Mermaid 图表支持（8 种）

graph LR
    A[flowchart 流程图] --- B[sequenceDiagram 时序图]
    B --- C[classDiagram 类图]
    C --- D[stateDiagram 状态图]
    D --- E[erDiagram ER图]
    E --- F[gantt 甘特图]
    F --- G[pie 饼图]
    G --- H[mindmap 思维导图]

Mermaid 注意事项

❌ 禁止	✅ 替代方案
节点标签中使用 {} 花括号	用普通文字替代
par...and...end 并行语法	改用 Note over X: 并行执行
过于复杂的时序图（10+ 角色）	控制在 8 个角色以内

---

常见问题排障

问题	原因	解决方案
认证失败 / Token 过期	未登录或 Token 已失效	执行 feishu-cli auth login --scopes "offline_access" 重新认证
Permission denied	应用权限未开通	回到第三步检查权限是否全部开通
文档创建成功但无法访问	未转移所有权	执行第九步的 perm add + perm transfer-owner
port 9768 already in use	回调端口被占用	检查是否有其他 feishu-cli 进程在运行
Mermaid 图表变代码块	语法不兼容飞书	检查是否用了 {} 或 par 语法
表格显示不全	飞书 API 限制 9 行/列	正常行为，会自动拆分
error=20027	开发者后台未启用该权限	回到第三步开通对应权限
应用未发布	应用还在"未发布"状态	回到第五步发布应用
Token 2 小时过期	没有加 offline_access scope	重新登录时加上 --scopes "offline_access"
图片上传失败	网络问题或图片不可访问	检查网络；失败图片会创建占位块

---

文件结构总览

搭建完成后，你电脑上与 feishu-cli 相关的文件：

~/.feishu-cli/
├── config.yaml     ← 应用凭证配置（App ID / App Secret）
└── token.json      ← OAuth Token（自动管理，登录后生成）

flowchart LR
    subgraph local[本地电脑]
        A[Markdown 文件] --> B[feishu-cli]
        C[config.yaml] --> B
        D[token.json] --> B
    end
    B -->|"doc import"| E[飞书云文档]
    B -->|"perm transfer-owner"| F[所有权转移给你]

---

快速命令速查表

# 检查认证状态
feishu-cli auth status

# 登录 / 重新登录
feishu-cli auth login --scopes "offline_access"

# 导入 MD 到飞书（创建新文档）
feishu-cli doc import "文件.md" --title "标题" --upload-images

# 导入 MD 到飞书（更新已有文档）
feishu-cli doc import "文件.md" --document-id <文档ID>

# 添加权限
feishu-cli perm add <文档ID> --doc-type docx --member-type email --member-id "邮箱" --perm full_access --notification

# 转移所有权
feishu-cli perm transfer-owner <文档ID> --doc-type docx --member-type email --member-id "邮箱" --notification

# 查看文档协作者
feishu-cli perm list <文档ID> --doc-type docx