飞书知识库文档批量上传指南#

🗂️ 基于三次实战经验沉淀（岗位资料47篇、面经47篇、经验贴44篇） 📅 更新于 2026-06-27 🎯 目标：快速、稳定地将本地 Markdown 文件批量上传至飞书知识库

一、整体流程概览#

1
1️⃣ 创建知识库节点 → 2️⃣ 复制文件到工作目录 → 3️⃣ 批量上传为飞书文档 → 4️⃣ 更新索引文档

二、前置准备#

2.1 查看知识库空间 ID#

1
lark-cli wiki +space-list

输出中找到目标知识库的 space_id，例如：

1
我的知识库 → space_id: 7655878760121502674

2.2 查看知识库根节点#

1
lark-cli wiki +node-list --space-id "<space_id>"

返回的 nodes 列表中，根目录下的节点会显示 parent_node_token 为根节点 token。

三、创建知识库节点#

3.1 创建分类节点（origin 类型）#

1
lark-cli wiki +node-create \
2
  --space-id "7655878760121502674" \
3
  --title "面经" \
4
  --node-type "origin" \
5
  --obj-type "docx"

参数说明：

--node-type origin：创建文件夹类型节点（可包含子文档）
--obj-type docx：节点关联的默认文档类型

返回示例：

1
{
2
  "ok": true,
3
  "data": {
4
    "node_token": "Gs8TwCHdiiv75wkYQUJcgWyHnGg",
5
    "title": "面经",
6
    "url": "https://my.feishu.cn/wiki/Gs8TwCHdiiv75wkYQUJcgWyHnGg"
7
  }
8
}

⚠️ 保存好 node_token！ 后续上传文档时要用作 --parent-token。

四、文件准备#

4.1 复制文件到可访问目录#

飞书 CLI 的 --content @file 必须使用相对路径，不能直接使用 Android 绝对路径。

1
# 创建临时工作目录
2
mkdir -p /home/mianjing
3

4
# 复制所有 .md 文件过去
5
cp /storage/emulated/0/小万工作间/面经/*.md /home/mianjing/

4.2 确认文件完整性#

1
ls /home/mianjing/*.md | wc -l
2
# 输出文件总数

五、批量上传文档#

5.1 核心命令#

1
cd /home/mianjing
2

3
lark-cli docs +create \
4
  --doc-format markdown \
5
  --parent-token "<node_token>" \
6
  --title "文档标题" \
7
  --content "@./文件名.md"

关键参数：

--doc-format markdown：以 Markdown 格式导入（本地 .md 文件直接用这个）
--parent-token：目标知识库节点的 token（步骤三中返回的）
--content @./xxx.md：相对路径！相对路径！相对路径！

5.2 ⚠️ 踩坑记录：文件路径问题#

1
# ❌ 错误写法——CLI 会报 invalid file path
2
--content @/storage/emulated/0/小万工作间/面经/xxx.md
3

4
# ✅ 正确写法——cd 到文件所在目录后用相对路径
5
cd /home/mianjing
6
--content @./xxx.md

错误信息：

1
--content: invalid file path "xxx": --file must be a relative path
2
within the current directory

5.3 批量上传脚本模板#

1
cd /home/mianjing
2

3
for f in *.md; do
4
  title="${f%.md}"
5
  echo "🔄 $title"
6

7
  result=$(lark-cli docs +create \
8
    --doc-format markdown \
9
    --parent-token "<node_token>" \
10
    --title "$title" \
11
    --content "@./$f" 2>&1)
12

13
  if echo "$result" | grep -q '"ok": true'; then
14
    echo "  ✅ 成功"
15
  else
16
    echo "  ⏳ 限流，等待重试..."
17
    sleep 8
18
    result=$(lark-cli docs +create \
19
      --doc-format markdown \
20
      --parent-token "<node_token>" \
21
      --title "$title" \
22
      --content "@./$f" 2>&1)
23
    if echo "$result" | grep -q '"ok": true'; then
24
      echo "  ✅ 重试成功"
25
    else
26
      echo "  ❌ 失败"
27
    fi
28
  fi
29

30
  sleep 2  # 间隔请求，避免限流
31
done

5.4 ⚠️ 踩坑记录：API 限流#

现象： 连续上传约 10 个文件后，所有请求返回 rate_limit 错误。

解决方案：

每上传一个文件后 sleep 2
限流后等待 8-10 秒 再重试
重试成功率接近 100%
宁可慢一点，不要并发上传（会全部限流）

六、验证上传结果#

6.1 查看节点下文档列表#

1
lark-cli wiki +node-list \
2
  --space-id "7655878760121502674" \
3
  --parent-node-token "<node_token>"

6.2 对比本地文件和已上传文件#

1
import subprocess, json, re, os
2

3
# 获取已上传的
4
r = subprocess.run(["lark-cli", "wiki", "+node-list",
5
    "--space-id", "7655878760121502674",
6
    "--parent-node-token", "<node_token>"],
7
    capture_output=True, text=True, timeout=15)
8
raw = r.stdout
9
m = re.search(r'\{.*', raw, re.DOTALL)
10
data = json.loads(m.group())
11
uploaded = set(n['title'] for n in data['data']['nodes'])
12

13
# 本地文件
14
local = set(f[:-3] for f in os.listdir("/home/mianjing")
15
            if f.endswith('.md'))
16

17
missing = local - uploaded
18
print(f"已上传: {len(uploaded)}")
19
print(f"本地: {len(local)}")
20
print(f"未同步: {len(missing)}")
21
for p in sorted(missing):
22
    print(f"  ⏳ {p}")

6.3 ⚠️ 踩坑记录：`node-list` 数据结构#

lark-cli wiki +node-list 返回的 JSON 结构是：

1
{
2
  "ok": true,
3
  "data": {
4
    "has_more": false,
5
    "nodes": [
6
      {
7
        "node_token": "xxx",
8
        "title": "文档标题",
9
        "node_type": "origin"
10
      }
11
    ],
12
    "page_token": "..."
13
  }
14
}

注意： 记录在 data.nodes 里，不是 data.records 或 data.data。

七、更新索引文档#

7.1 获取当前索引文档内容#

1
lark-cli docs +fetch \
2
  --doc "<doc_token>" \
3
  --doc-format markdown

返回的 JSON 中，内容在 data.document.content。

注意 revision_id： 每次更新后 revision 会递增，更新时需要传入最新的 revision。

7.2 获取节点下所有文档的链接#

1
import subprocess, json, re
2

3
# 处理分页
4
all_nodes = []
5
page_token = None
6
while True:
7
    cmd = ["lark-cli", "wiki", "+node-list",
8
        "--space-id", "7655878760121502674",
9
        "--parent-node-token", "<node_token>"]
10
    if page_token:
11
        cmd += ["--page-token", page_token]
12

13
    r = subprocess.run(cmd, capture_output=True, text=True, timeout=15)
14
    raw = r.stdout
15
    m = re.search(r'\{.*', raw, re.DOTALL)
16
    data = json.loads(m.group())
17
    all_nodes.extend(data['data']['nodes'])
18

19
    if data['data'].get('has_more') and data['data'].get('page_token'):
20
        page_token = data['data']['page_token']
21
    else:
22
        break
23

24
# 文档链接格式：https://my.feishu.cn/wiki/<node_token>
25
for n in sorted(all_nodes, key=lambda x: x['title']):
26
    print(f"- [{n['title']}](https://my.feishu.cn/wiki/{n['node_token']})")

7.3 覆盖更新索引文档#

1
lark-cli docs +update \
2
  --doc "<doc_token>" \
3
  --command overwrite \
4
  --doc-format markdown \
5
  --content "<完整的新文档内容>" \
6
  --revision-id <latest_revision>

7.4 ⚠️ 踩坑记录：`overwrite` vs `str_replace`#

overwrite：用 --content 完全替换文档内容。适合大段增删改。
str_replace：替换文档中的指定文本。适合小范围修改（如更新篇数）。
replace_all ❌ 不存在这个命令！ 会报 invalid value "replace_all"。

更新文档总数的示例：

1
# 先找到文档中的旧数字，用 str_replace 精准替换
2
lark-cli docs +update \
3
  --doc "<doc_token>" \
4
  --command str_replace \
5
  --pattern "🗂️ 共 73 篇文档" \
6
  --content "🗂️ 共 120 篇文档" \
7
  --revision-id <rev>

八、最佳实践总结#

8.1 建议的上传节奏#

批次	文件数	间隔	预计耗时
第一批（热身）	5 个	2 秒	~15s
第二批	10 个	2 秒	~25s
第三批及以后	每次 10-15 个	2-3 秒	~1min/批
限流后重试	等待 8-10 秒	-	-

40-50 个文件的总耗时约 5-8 分钟。

8.2 批量操作流程速查#

1
# 1. 创建节点
2
lark-cli wiki +node-create --space-id "xxx" --title "节点名" --node-type origin --obj-type docx
3

4
# 2. 复制文件
5
mkdir -p /home/temp && cp /storage/emulated/0/小万工作间/xxx/*.md /home/temp/
6

7
# 3. 批量上传（cd 到目录后用 for 循环）
8
cd /home/temp && for f in *.md; do ... done
9

10
# 4. 验证
11
lark-cli wiki +node-list --space-id "xxx" --parent-node-token "xxx" | python3 -c "..."
12

13
# 5. 更新索引
14
lark-cli docs +update --doc "xxx" --command overwrite --doc-format markdown --content "..." --revision-id x

8.3 坑点速查表#

坑	表现	解决
`--content @file` 路径错误	`invalid file path`	用相对路径，先 cd 到目录
API 限流	`rate_limit` 错误	每文件间隔 2s，限流后等 8-10s 重试
`node-list` 数据路径	`KeyError: 'records'`	记录在 `data.nodes` 里
`replace_all` 不存在	`invalid value`	用 `overwrite` 或 `str_replace`
索引 revision 过期	更新失败	先 fetch 获取最新 revision
仪表盘统计卡片	”数据加载失败”	配置正确但客户端渲染卡顿，刷新即可

九、常用命令速查#

1
# 知识库操作
2
lark-cli wiki +space-list                          # 列出知识库空间
3
lark-cli wiki +node-list --space-id "xxx"          # 列出根节点
4
lark-cli wiki +node-list --space-id "xxx" --parent-node-token "xxx"  # 列出子节点
5
lark-cli wiki +node-create --space-id "xxx" --title "xx" --node-type origin --obj-type docx  # 创建节点
6

7
# 文档操作
8
lark-cli docs +create --doc-format markdown --parent-token "xxx" --title "xx" --content @./xx.md  # 创建文档
9
lark-cli docs +fetch --doc "xxx" --doc-format markdown  # 获取文档内容
10
lark-cli docs +update --doc "xxx" --command overwrite --doc-format markdown --content "..." --revision-id x  # 更新文档
11

12
# 多维表格操作
13
lark-cli base +field-list --base-token "xxx" --table-id "xxx"  # 列出字段
14
lark-cli base +record-list --base-token "xxx" --table-id "xxx" --format json  # 列出记录
15
lark-cli base +record-upsert --base-token "xxx" --table-id "xxx" --record-id "xxx" --json '{"字段":"值"}'  # 更新单条
16
lark-cli base +record-batch-update --base-token "xxx" --table-id "xxx" --json @./file.json  # 批量更新

💡 核心原则： 耐心比速度重要——每次间隔几秒，限流了等一会再重试，反而比盲目快冲更快完成全部上传。

Music

Music

飞书知识库文档批量上传指南#

一、整体流程概览#

二、前置准备#

2.1 查看知识库空间 ID#

2.2 查看知识库根节点#

三、创建知识库节点#

3.1 创建分类节点（origin 类型）#

四、文件准备#

4.1 复制文件到可访问目录#

4.2 确认文件完整性#

五、批量上传文档#

5.1 核心命令#

5.2 ⚠️ 踩坑记录：文件路径问题#

5.3 批量上传脚本模板#

5.4 ⚠️ 踩坑记录：API 限流#

六、验证上传结果#

6.1 查看节点下文档列表#

6.2 对比本地文件和已上传文件#

6.3 ⚠️ 踩坑记录：`node-list` 数据结构#

七、更新索引文档#

7.1 获取当前索引文档内容#

7.2 获取节点下所有文档的链接#

7.3 覆盖更新索引文档#

7.4 ⚠️ 踩坑记录：`overwrite` vs `str_replace`#

八、最佳实践总结#

8.1 建议的上传节奏#

8.2 批量操作流程速查#

8.3 坑点速查表#

九、常用命令速查#

Share Article

Music

Table of Contents

Music

Music

飞书知识库文档批量上传指南

飞书知识库文档批量上传指南#

一、整体流程概览#

二、前置准备#

2.1 查看知识库空间 ID#

2.2 查看知识库根节点#

三、创建知识库节点#

3.1 创建分类节点（origin 类型）#

四、文件准备#

4.1 复制文件到可访问目录#

4.2 确认文件完整性#

五、批量上传文档#

5.1 核心命令#

5.2 ⚠️ 踩坑记录：文件路径问题#

5.3 批量上传脚本模板#

5.4 ⚠️ 踩坑记录：API 限流#

六、验证上传结果#

6.1 查看节点下文档列表#

6.2 对比本地文件和已上传文件#

6.3 ⚠️ 踩坑记录：node-list 数据结构#

七、更新索引文档#

7.1 获取当前索引文档内容#

7.2 获取节点下所有文档的链接#

7.3 覆盖更新索引文档#

7.4 ⚠️ 踩坑记录：overwrite vs str_replace#

八、最佳实践总结#

8.1 建议的上传节奏#

8.2 批量操作流程速查#

8.3 坑点速查表#

九、常用命令速查#

Share Article

Music

Table of Contents

6.3 ⚠️ 踩坑记录：`node-list` 数据结构#

7.4 ⚠️ 踩坑记录：`overwrite` vs `str_replace`#