Notion Blocks API 递归树读写、2000 字符分片与富文本(Rich Text)无损转换工程实战

2026 年 11 月 20 日

一、为什么直接调用 Notion API 读写页面正文总是“丢一半或报 400”? #

许多团队在搭建文档自动化同步、企业知识库 RAG 检索或 AI 自动写周报系统时,只调通了数据库属性读写(Data Sources API 迁移规范),但在真正读写页面正文(Page Content)时频繁踩坑,常见报错包括:

  1. 多层嵌套块抓不全:仅请求一次 GET /v1/blocks/{page_id}/children 只能拿到最顶层块。一旦页面里包含折叠列表(Toggles)、多栏布局(多栏与排版)、Callout 高亮块或表格(table),内部文字全数遗漏;
  2. 2000 字符超限直接 validation_error:Notion API 规定单个 rich_text 对象的 text.content 长度严格上限为 2000 个字符。同步长段落、日志或代码片段时若未做切片,整批写入请求会被直接拒绝(文本字段规范可参阅 Name 与 Text 属性治理);
  3. 单次写入超过 100 个 Block 触发拦截:PATCH /v1/blocks/{block_id}/children 单次最多追加 100 个子块,且单页总块数过大时会引发前端渲染卡顿甚至超时。

要构建稳定可靠的页面正文管道,必须先厘清 Notion 常用块类型与 API 的读写能力边界(集成鉴权准备参见 创建 Notion API 集成):

Notion Block 类型 API type 标识 是否含子块(has_children) Markdown 双向映射注意事项 工程读写避坑要点
段落 / 标题 / 列表 paragraph / heading_1~3 / bulleted_list_item 列表项与可折叠标题支持子块 需提取 rich_text 数组内联样式(加粗、链接、行内代码) 单个 rich_text 元素 ≤ 2000 字;heading 开启 is_toggleable 后才挂子块
折叠块 / 高亮块 toggle / callout 是(必须递归拉取) Markdown 原生无标准 callout,通常降级为 > [!NOTE] 引用块 创建时可在 children 内顺带嵌套 2 层,深层须拿到新 id 后二次追加
多栏容器与列 column_list / column 是(两层嵌套) 多栏在导出 Markdown 时会拍平为单列流式文本 API 写入 column_list 时至少需包含 2 个 column,且每个 column 至少含 1 个子块
普通表格与行 table / table_row 是(行作为子块) 单元格内为二维 rich_text 数组,不支持跨行合并 创建 table 时必须显式指定 table_width 与 children 行数据
同步块 synced_block 仅源块含子块 引用块 synced_from.block_id 指向源块 UUID 修改内容必须写入源块 ID,直接修改引用实例会报错(参见 同步块指南)
子库与文件嵌入 child_database / image / embed 否(只读结构或外链) child_database 仅返回标题,须转调 Data Sources API 查行 Notion 托管图片返回带 1 小时过期的签名 URL,长期归档须立即转存对象存储

二、Notion Blocks API 四步无损读写工程规范 #

在企业级知识同步或备份流水线中(导出归档规范可参阅 导出页面为 Markdown 与 批量导出无损迁移实战),建议严格执行以下四步标准作业流程:

  1. 深度优先递归拉取 + 游标分页(Pagination):
    • GET /v1/blocks/{block_id}/children?page_size=100 每次最多返回 100 个直接子块。当响应中 has_more 为 true 时,必须携带 next_cursor 循环翻页;
    • 对每个返回块检查 block["has_children"] == True,若为 True 且块类型不是 child_page / child_database(避免跨页面无边界爬取),立即递归向下抓取子块;若遇到 synced_block 且 synced_from 非空,则重定向抓取 synced_from["block_id"]。
  2. Rich Text 安全分片算法(2000 字符防爆器):
    • 写入任何长文本前,按 1800~1950 字符阈值切分为多个 {"type": "text", "text": {"content": chunk}} 对象塞入同一个 rich_text 数组;
    • 尽量在换行符或句号处边界切分,避免截断 Markdown 语法标记或 emoji 代理对(Surrogate Pair)。
  3. 100 块分批写入与深层结构两段式创建:
    • 将待写入的顶层块列表按每批 <= 100 个切片,串行调用 PATCH /v1/blocks/{page_id}/children;
    • 若子块嵌套超过 2 层,先创建父块并从响应 results 中解析出新生成的 block_id,再对 block_id 追加第 3 层及更深子块。
  4. 严格遵守平均 3 req/s 速率与 429 退避重试:
    • Notion API 对单集成令牌限制约为平均每秒 3 次请求。递归读深层页面极易触发 HTTP 429 Too Many Requests,必须在客户端读取响应头 Retry-After(单位:秒)并执行等待重试。

三、Notion API 2025-09-03 实战:递归遍历与安全分片写入脚本 #

下面是一套可直接用于生产环境的 Python 工具模块,统一使用 Notion-Version: 2025-09-03,完整实现“带 429 退避的递归拉取整棵块树”与“2000 字符分片 + 100 块分批追加”两大核心能力:

import os
import time
import httpx
from typing import Any

NOTION_TOKEN = os.environ["NOTION_TOKEN"]
HEADERS = {
    "Authorization": f"Bearer {NOTION_TOKEN}",
    "Notion-Version": "2025-09-03",
    "Content-Type": "application/json",
}

def request_with_retry(client: httpx.Client, method: str, url: str, **kwargs: Any) -> dict[str, Any]:
    """带 429 Retry-After 退避与瞬断重试的 Notion API 请求封装"""
    for attempt in range(5):
        resp = client.request(method, url, headers=HEADERS, timeout=20.0, **kwargs)
        if resp.status_code == 429:
            wait_sec = float(resp.headers.get("Retry-After", 2 ** attempt))
            time.sleep(wait_sec + 0.2)
            continue
        if resp.status_code in (500, 502, 503, 504) and attempt < 4:
            time.sleep(1.5 * (attempt + 1))
            continue
        resp.raise_for_status()
        return resp.json()
    raise RuntimeError(f"Notion API 请求在多次重试后仍失败: {url}")

def fetch_block_tree(client: httpx.Client, block_id: str, depth: int = 0, max_depth: int = 8) -> list[dict[str, Any]]:
    """递归拉取页面/块下所有嵌套子块(自动处理游标分页与同步块引用)"""
    if depth > max_depth:
        return []

    children: list[dict[str, Any]] = []
    next_cursor: str | None = None

    while True:
        params: dict[str, Any] = {"page_size": 100}
        if next_cursor:
            params["start_cursor"] = next_cursor

        data = request_with_retry(
            client,
            "GET",
            f"https://api.notion.com/v1/blocks/{block_id}/children",
            params=params,
        )
        for blk in data.get("results", []):
            btype = blk.get("type")
            # 同步块若为引用实例,需指向原块 ID 才能拉到真实子块
            if btype == "synced_block" and blk["synced_block"].get("synced_from"):
                source_id = blk["synced_block"]["synced_from"]["block_id"]
                blk["children_tree"] = fetch_block_tree(client, source_id, depth + 1, max_depth)
            elif blk.get("has_children") and btype not in ("child_page", "child_database"):
                blk["children_tree"] = fetch_block_tree(client, blk["id"], depth + 1, max_depth)
            children.append(blk)

        if not data.get("has_more"):
            break
        next_cursor = data.get("next_cursor")

    return children

def chunk_rich_text(text: str, limit: int = 1900) -> list[dict[str, Any]]:
    """按 <= 2000 字符上限安全切分长文本,构造标准 rich_text 数组"""
    if not text:
        return [{"type": "text", "text": {"content": ""}}]
    chunks: list[dict[str, Any]] = []
    start = 0
    while start < len(text):
        end = min(start + limit, len(text))
        if end < len(text):
            newline_pos = text.rfind("\n", start, end)
            if newline_pos > start + limit // 2:
                end = newline_pos + 1
        chunks.append({"type": "text", "text": {"content": text[start:end]}})
        start = end
    return chunks

def append_blocks_in_batches(client: httpx.Client, parent_id: str, blocks: list[dict[str, Any]]) -> None:
    """按每批最多 100 个 Block 安全追加到目标页面或父块"""
    for i in range(0, len(blocks), 100):
        batch = blocks[i : i + 100]
        request_with_retry(
            client,
            "PATCH",
            f"https://api.notion.com/v1/blocks/{parent_id}/children",
            json={"children": batch},
        )
        time.sleep(0.35)  # 主动控制在 ~3 req/s 安全水线内

四、Formula 2.0 实战:正文体量膨胀预警与同步健康度门禁闭环 #

当大量外部文本通过 Blocks API 持续回写到 Notion 知识库或工单库时,如果单页 Block 数量失控(例如累计超过 1500 个块),桌面端和移动端打开该页就会出现明显卡顿;而若上游同步任务中断,页内正文与外部数据源就会出现长期漂移。

我们可以在文档台账库中增加 Block 总数(Number)、嵌套最大深度(Number)、同步状态(Status)、最近同步时间(Date),并配置如下 正文健康度门禁 Formula 2.0 属性(公式语法可参阅 Formula 2.0 速查手册 与 Formula 工程治理实战):

lets(
  blkCount, prop("Block 总数"),
  maxDepth, prop("嵌套最大深度"),
  syncStatus, format(prop("同步状态")),
  lastSync, prop("最近同步时间"),
  hoursAgo, if(!empty(lastSync), dateBetween(now(), lastSync, "hours"), 9999),

  ifs(
    syncStatus == "同步失败",
      style("🔴 同步失败:检查 2000 字符分片或 429 限流告警", "red", "bold", "red_background"),
    blkCount >= 1500,
      style("🟠 块数超载(" + format(blkCount) + " 块):建议拆分子页面防卡顿", "orange", "bold", "yellow_background"),
    maxDepth >= 6,
      style("🟡 深层嵌套(" + format(maxDepth) + " 层):API 同步耗时风险高", "orange", "bold"),
    hoursAgo > 72,
      style("⏳ 同步陈旧:已超 " + format(hoursAgo) + " 小时未增量拉取", "gray"),
    style("🟢 正文树健康 · " + format(blkCount) + " Blocks", "green")
  )
)

常见 API 写入报错与网络同步超时排查,请对照 Notion 常见报错与故障诊断手册 与 数据库架构选型速查 进行联动排障。


五、生产环境高频踩坑清单与上线前核验要点 #

在将 Blocks API 同步管道正式部署至生产环境(如定时构建静态站、企业级知识库增量索引或自动周报推送)前,建议逐项完成以下工程验收,避免运行后出现“静默漏字”或数据错位:

  1. 区分 child_page 与容器块边界,防止无限递归爬穿整个工作区:
    • 当你在遍历一个汇总页面时,如果里面嵌入了大量下属子页面(child_page)或行内数据库(child_database),它们的 has_children 同样可能返回 true。如果代码不加以类型过滤,单次同步会雪崩式触发数千次请求并迅速耗尽速率配额。务必在递归入口显式跳过这两类跨文档引用节点,仅按需单独调度页面任务队列。
  2. 注意 code 代码块、equation 公式块与 link_preview 的只读或长度特性:
    • 代码块内部同样遵守 rich_text 单个元素 <= 2000 字符的限制,若外部脚本把几万行日志文件整体塞入一个 code 块,同样需要走 chunk_rich_text 切分;
    • link_preview 属于受外部服务鉴权保护的只读块,API 无法直接构造创建,写入外部链接时应统一降级使用 bookmark 或带超链接的 paragraph。
  3. 增量更新优先采用“按块精确 Patch/Delete”,避免全页清空重建:
    • 若直接循环删除旧页所有顶层块再重新写入,不仅消耗双倍 API 配额,还会彻底销毁同事留在原段落上的行内评论(Comments)与块级锚点引用链接。建议在本地维护一套基于 block_id 与内容哈希(SHA-256)的差异比对表,仅对发生变更的段落执行局部更新,从而最大限度保留协作上下文与版本历史。

❓ 常见问题与答疑 (FAQ)

高频疑难解析与避坑指南
A

完全不需要。绝大多数核心功能在免费 Free 计划中均可完整体验与实操练习,无需额外付费购买 Plus 或团队版。