Notion 与 Logseq / 思源笔记(SiYuan)深度架构对比与双向链接知识库无损迁移实战:从大纲块引擎解析、EDN/JSON 数据清洗到 Formula 2.0 迁移质检看板

2026 年 11 月 18 日

一、核心痛点与底层架构对比:为什么从 Logseq / 思源笔记迁往 Notion? #

在个人知识管理(PKM)与团队知识协同领域,Logseq 凭借基于本地 Markdown/Org-mode 文件的大纲(Outliner)与块级双向引用深受极客喜爱,思源笔记(SiYuan) 则以本地 SQLite + .sy JSON 块引擎、端到端加密与强大的本地离线检索在国内拥有大量用户。然而,当知识积累迈向跨成员协作、多维项目关系管理、SaaS 外部集成与结构化数据大盘时,纯本地大纲工具往往会遭遇三大瓶颈:

  • 协作与权限颗粒度受限:Logseq 依赖 Git 或第三方网盘同步,多人同时编辑同一日记或长文档极易产生冲突;思源笔记虽支持自建服务端与云端同步,但缺乏 Notion 原生的单页访客权限(Guest)、团队空间隔离(Teamspaces)与细粒度数据库属性视图;
  • 非结构化大纲难以直接驱动复杂业务流:在 Logseq 中用 #tag 或 property:: value 标记的读书笔记、任务与客户线索,虽然能通过 Datalog 查询展示,但远不如 Notion 数据库的 Relation 双向关联、Rollup 穿透与 Formula 2.0 动态计算直观易用;
  • 跨平台连接生态差距:Notion 原生支持官方 REST API、Webhook、Notion Forms 表单与海量第三方自动化平台联动(如对比桌面本地 Markdown 工具,也可参考 Notion 与 Obsidian 深度架构对比实战 与 Notion 与 Wolai / FlowUs 无损迁移实战)。

如果直接将 Logseq 的 pages/ 目录或思源笔记导出的 Markdown 压缩包拖拽进 Notion 原生导入器,会出现满屏 id:: 65a1... 冗余属性代码、((UUID)) 块引用沦为死文本、[[页面双链]] 全部失活、以及本地 assets/ 图片相对路径断裂等问题。因此,必须采用 「两阶段预处理清洗 + Notion API 幂等写入 + Formula 2.0 质检审计」 工程化管线。

架构维度 Notion Logseq 思源笔记(SiYuan)
底层数据模型 云端关系型 Block + 多维 Database(JSON 对象树) 本地纯文本大纲(Markdown / Org-mode + EDN 索引) 本地块级 JSON(.sy 文件)+ SQLite 全文索引
存储与隐私模式 云端托管为主,企业级支持 SAML SSO 与审计日志 100% 本地明文文件夹,依赖 iCloud / Git 同步 本地优先 + 支持私有对象存储与端到端加密
双链与块引用机制 @页面引用、Backlinks 与 Synced Block 同步块 [[Page]] 双链与 ((block-uuid)) 任意块嵌入 ((id '锚文本')) 块引用与虚线双向链接图谱
结构化数据能力 原生 Relation / Rollup / Formula 2.0 / 多视图 页面属性 key:: value + Datalog 高级查询 数据库(Attribute View)+ SQL 嵌入式查询块
外部集成与生态 官方 REST API、Webhook、AI Connectors 全生态 本地插件系统(JS)+ 开源社区生态 本地 Kernel HTTP API + 集市插件生态

二、迁移前语法映射规范:大纲块、双链与任务状态的无损对齐 #

在编写清洗脚本前,务必确立源平台专有语法向 Notion 原生 Block 与数据库属性的映射契约(更多导入基础参阅 导入数据基础指南 与 双向链接官方指南):

源平台语法(Logseq / 思源笔记) 典型特征示例 Notion 无损映射目标 脚本清洗与转换动作
Logseq 块级 UUID 与折叠状态 id:: 64f2... / collapsed:: true 清理或转为 Toggle 折叠块 正则剥离 id:: 与 logbook 耗时区块;折叠项转为 toggle Block
Logseq 页面属性头 tags:: #PKM, #效率 / author:: 某作者 Notion Database 原生 Multi-select / Text 属性 解析文件顶部 key:: value 键值对写入页面 properties
Logseq 任务标记与优先级 TODO [#A] 整理文献 / DONE Notion to_do 块或数据库 Status 属性 DONE 映射为 checked: true,其余转为未勾选状态并保留优先级标签
双链 [[Page]] 与块引用 ((id)) 参考 [[Zettelkasten]] / ((202305-abc)) Notion @Mention 页面提及或标准超链接 两阶段映射:先建页收集 Title -> Page URL 字典再回填替换
思源笔记导出标签与块属性 {: id="2024..."} / #标签# 清理 IAL 属性后缀,提取 #标签# 至 Tags 列 正则剔除 Kramdown IAL 花括号属性块,统一提取分类标签
本地附件与图片路径 ![图](../assets/img_123.png) Notion 托管图片或外部永久图床 URL 扫描本地相对路径,上传至 OSS/R2 CDN 后重写为 HTTPS 图链

三、分步骤实操:两阶段脚本清洗与 Notion API 批量入库 #

步骤 1:在 Notion 建立迁移验收总库(DB_PKM_Migration_Hub) #

在 Notion 开发者后台创建一个内部集成(参阅 创建 Notion API 集成指南),并在目标工作区参照 企业级数据库架构规范 新建 DB_PKM_Migration_Hub 数据库,包含以下核心属性:

Notion 属性名 属性类型 迁移与质检用途 校验要求
笔记标题 Title 原 Logseq 文件名或思源文档 H1 标题 去除 .md 后缀及 URL 编码字符
Source_Key Text 幂等防重主键(如 logseq:pages/zettelkasten) 写入前查重,确保脚本重跑零重复建页
源平台 Select Logseq / 思源笔记 / Journals日记 区分笔记来源便于分类筛选
知识标签 Multi-select 从原文件 tags:: 或 #标签# 自动提取的分类标签 自动去除 # 号并拆分为标准数组
关联引用页面 Relation 自关联(Self-Relation),记录解析 [[双链]] 命中的页面 构建 Notion 原生双向图谱
未解析双链数 Number 正文中仍残留的未命中 [[...]] 或 ((...)) 数量 大于 0 时在质检视图亮灯人工复核
失效本地图链数 Number 脚本未在 assets/ 中找到实体文件的图片数量 防止静默丢图导致知识资产受损
正文有效字数 Number 清洗掉元数据与空行后的纯文本字符长度 用于识别空壳索引页
迁移验收状态 Status 待质检 / 已人工复核 / 已归入正式库 驱动迁移验收闭环

步骤 2:运行 Python 两阶段清洗与 API 写入脚本 #

以下脚本完成核心第一阶段清洗与入库:读取 Logseq / 思源笔记导出目录 -> 剥离 id::、collapsed:: 与 Kramdown {: ...} 冗余属性 -> 解析页面属性与双链数量 -> 按每段 ≤ 2000 字符、单次 ≤ 100 块安全调用 Notion API 写入(限流避坑详情参阅 Notion API 速率限制与容错架构 与 通用跨平台迁移实战):

# migrate_outliner_to_notion.py
import os
import re
import time
import glob
import requests

NOTION_TOKEN = os.environ["NOTION_TOKEN"]
DATABASE_ID = os.environ["NOTION_MIGRATION_DB_ID"]
SOURCE_DIR = "./export_markdown"  # Logseq pages/ 或 思源导出目录
CDN_BASE_URL = "https://cdn.example.com/pkm-assets"  # 预先同步 assets/ 后的对象存储前缀

HEADERS = {
    "Authorization": f"Bearer {NOTION_TOKEN}",
    "Notion-Version": "2022-06-28",
    "Content-Type": "application/json",
}

def notion_request(method, endpoint, payload=None):
    url = f"https://api.notion.com/v1{endpoint}"
    for attempt in range(4):
        resp = requests.request(method, url, headers=HEADERS, json=payload, timeout=20)
        if resp.status_code == 429:
            wait = int(resp.headers.get("Retry-After", 2))
            time.sleep(wait)
            continue
        resp.raise_for_status()
        time.sleep(0.35)  # 遵守 3 req/s 平均速率上限
        return resp.json()
    raise RuntimeError(f"Notion API 请求多次限流失败: {endpoint}")

def clean_outliner_markdown(raw_text, local_assets_set):
    """清洗 Logseq 属性行、思源 IAL 标记,并统计未解析双链与缺失图片"""
    tags = []
    body_lines = []
    unresolved_links = 0
    missing_images = 0

    for line in raw_text.splitlines():
        # 1. 提取 Logseq 顶部属性 tags::
        m_tags = re.match(r"^\s*tags::\s*(.+)$", line)
        if m_tags:
            found = [t.strip().lstrip("#") for t in re.split(r"[,,\s]+", m_tags.group(1)) if t.strip()]
            tags.extend(found)
            continue
        # 2. 剔除 Logseq 内部块元数据(id::, collapsed::, :LOGBOOK: 等)
        if re.match(r"^\s*(id|collapsed|heading|background-color)::\s*", line):
            continue
        if line.strip() in (":LOGBOOK:", ":END:") or line.strip().startswith("CLOCK:"):
            continue
        # 3. 剔除思源笔记 Kramdown IAL 属性后缀 {: id="xxx" ...}
        line = re.sub(r"\{:\s*[^}]+\}", "", line)
        # 4. 转换 Logseq 任务语法 "- TODO " / "- DONE "
        line = re.sub(r"^(\s*)-\s+(?:TODO|LATER|NOW|DOING)\s+", r"\1- [ ] ", line)
        line = re.sub(r"^(\s*)-\s+DONE\s+", r"\1- [x] ", line)
        # 5. 检查本地图片相对路径并重写为永久图床 URL
        def replace_img(match):
            nonlocal missing_images
            alt, img_path = match.group(1), match.group(2).strip()
            filename = os.path.basename(img_path.split("?")[0])
            if img_path.startswith("http"):
                return match.group(0)
            if filename in local_assets_set:
                return f"![{alt}]({CDN_BASE_URL}/{filename})"
            missing_images += 1
            return f"[缺失图片: {filename}]"

        line = re.sub(r"!\[([^\]]*)\]\(([^)]+)\)", replace_img, line)
        # 6. 统计残留未映射的 ((block-uuid)) 或 [[双链]]
        unresolved_links += len(re.findall(r"\(\([0-9a-f-]{8,}\)\)", line))
        body_lines.append(line)

    cleaned = "\n".join(body_lines).strip()
    return cleaned, list(dict.fromkeys(tags)), unresolved_links, missing_images

def text_to_notion_blocks(cleaned_text):
    """将清洗后文本拆分为合规 Notion Block(单段严格 <= 1900 字符)"""
    blocks = []
    for line in cleaned_text.splitlines():
        s = line.rstrip()
        if not s:
            continue
        # 剥离大纲前导 "- " 转换为 bulleted_list_item
        stripped = s.lstrip()
        if stripped.startswith("- [ ] ") or stripped.startswith("- [x] "):
            checked = stripped.startswith("- [x] ")
            content = stripped[6:][:1900]
            blocks.append({"object": "block", "type": "to_do", "to_do": {"checked": checked, "rich_text": [{"text": {"content": content}}]}})
        elif stripped.startswith("- "):
            blocks.append({"object": "block", "type": "bulleted_list_item", "bulleted_list_item": {"rich_text": [{"text": {"content": stripped[2:][:1900]}}]}})
        elif stripped.startswith("## "):
            blocks.append({"object": "block", "type": "heading_2", "heading_2": {"rich_text": [{"text": {"content": stripped[3:][:1900]}}]}})
        else:
            blocks.append({"object": "block", "type": "paragraph", "paragraph": {"rich_text": [{"text": {"content": stripped[:1900]}}]}})
    return blocks

def run_migration():
    assets_dir = os.path.join(SOURCE_DIR, "assets")
    local_assets = set(os.listdir(assets_dir)) if os.path.isdir(assets_dir) else set()

    for md_path in glob.glob(os.path.join(SOURCE_DIR, "**", "*.md"), recursive=True):
        rel_key = f"pkm:{os.path.relpath(md_path, SOURCE_DIR)}"
        title = os.path.splitext(os.path.basename(md_path))[0]
        with open(md_path, "r", encoding="utf-8") as f:
            raw = f.read()

        cleaned, tags, unresolved, missing_imgs = clean_outliner_markdown(raw, local_assets)
        blocks = text_to_notion_blocks(cleaned)

        # 幂等查重
        q = notion_request("POST", f"/databases/{DATABASE_ID}/query", {
            "filter": {"property": "Source_Key", "rich_text": {"equals": rel_key}}
        })
        if q.get("results"):
            continue

        # 写入首批最多 90 个块,超长部分循环 append
        created = notion_request("POST", "/pages", {
            "parent": {"database_id": DATABASE_ID},
            "properties": {
                "笔记标题": {"title": [{"text": {"content": title[:200]}}]},
                "Source_Key": {"rich_text": [{"text": {"content": rel_key}}]},
                "源平台": {"select": {"name": "Logseq"}},
                "知识标签": {"multi_select": [{"name": t[:50]} for t in tags[:10]]},
                "未解析双链数": {"number": unresolved},
                "失效本地图链数": {"number": missing_imgs},
                "正文有效字数": {"number": len(cleaned)},
                "迁移验收状态": {"status": {"name": "待质检"}},
            },
            "children": blocks[:90],
        })
        for idx in range(90, len(blocks), 90):
            notion_request("PATCH", f"/blocks/{created['id']}/children", {"children": blocks[idx:idx + 90]})

if __name__ == "__main__":
    run_migration()

第二阶段图谱回填提示:完成首轮全量写入并获取所有页面的 {title: page_id} 字典后,二次遍历正文中的 [[PageName]],通过 pages.update 将命中的关联页面写入 关联引用页面(Relation 属性),即可在 Notion 中重建出结构化的知识网络。


四、Formula 2.0 迁移质检门禁与知识资产健康度看板 #

面对数千篇迁移入库的笔记,不可能逐篇人工翻阅。在 DB_PKM_Migration_Hub 中配置 Formula 2.0 属性 迁移质检门禁(语法详查 Notion 公式基础 与 Formula 2.0 速查手册),自动识别断链、丢图、空壳页面与孤岛节点:

lets(
  linksBroken, prop("未解析双链数"),
  imgsBroken, prop("失效本地图链数"),
  wordCount, prop("正文有效字数"),
  relCount, prop("关联引用页面").length(),
  status, prop("迁移验收状态"),

  ifs(
    imgsBroken > 0,
      style("🚨 存在 " + imgsBroken + " 张本地图片缺失 · 严禁删除原本地库", "red", "bold"),
    linksBroken > 0,
      style("🟠 残留 " + linksBroken + " 处未解析块引用 ((uuid)) · 需人工补链", "orange", "bold"),
    wordCount < 30 && relCount == 0,
      style("🟡 空壳或纯索引孤岛页(仅 " + wordCount + " 字)· 建议合并或清理", "orange"),
    status == "已归入正式库" && relCount >= 1,
      style("🟢 迁移完好 · 图链完整且已建立 " + relCount + " 条双链关联", "green", "bold"),
    status == "已归入正式库",
      style("🔵 内容完好 · 建议补充至少 1 条关联关系消除知识孤岛", "blue"),
    style("⏳ 待人工抽检核验 · 图文指标初步正常", "gray")
  )
)

五、迁移高频故障排查与双平台共存建议(Checklist) #

在执行 Logseq 或思源笔记向 Notion 迁移及后续日常运维时,若遇以下典型异常可快速排查(更多报错参阅 Notion 常见故障排查手册):

  1. Logseq pages/ 目录包含大量带有 %2F 编码的文件名(如 React%2FHooks.md)导致双链无法匹配:
    • 根因:Logseq 使用斜杠表示命名空间层级(Namespace),在文件系统存储时会将 / 自动转义为 %2F;
    • 解法:在解析 title 与构建双链映射字典时先调用 urllib.parse.unquote(title) 还原真实命名空间路径,并在 Notion 中按顶级命名空间归档至对应目录或 Tag。
  2. 思源笔记导出 Markdown 后,公式块与代码块高亮错乱或出现成串 $$ 换行异常:
    • 根因:思源笔记内部采用行内块渲染部分行间 LaTeX 公式且带有缩进,与 Notion equation 块规范不完全一致;
    • 解法:在清洗脚本中匹配独立成段的 $$\n...\n$$ 块,将其显式映射为 Notion 原生 equation Block 对象而非普通段落文本。
  3. 导入超深嵌套的大纲列表(超过 4~5 级缩进)时 Notion API 报错 400 validation_error:
    • 根因:Notion API 单次请求限制最多嵌套 2 层 children 子块(即父块 -> 子块 -> 孙块),直接提交 5 层嵌套 JSON 会被网关拒绝;
    • 解法:将 3 层及以上的深层大纲先拆平或先创建顶级页面,再递归按子块 block_id 逐层调用 PATCH /blocks/{id}/children 挂载,或者将折叠长分支收口进 Notion toggle 切换块(用法参考 切换器官方指南)。
  4. 思源笔记 / Logseq 重度用户如何与 Notion 长期混合共存?
    • 最佳实践:将 隐私草稿、离线科研笔记、千行大纲头脑风暴 留在本地 Logseq/思源,仅将 已完成沉淀的常青笔记(Evergreen Notes)、团队协作 SOP 与项目台账 通过上述单向增量脚本(锚定 Source_Key 幂等更新)同步至 Notion 对外协作空间,兼顾本地隐私安全与云端协同效率。

❓ 常见问题与答疑 (FAQ)

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

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