Notion 与 Craft 深度架构对比与无损迁移实战:从嵌套卡片导出、Markdown 块结构映射、Notion API 2025-09-03 批量迁入到 Formula 2.0 迁移质检闭环

2026 年 11 月 20 日

一、核心架构对比:Notion 关系型工作台 vs Craft 苹果生态美学文档 #

在 Apple 生态(macOS / iPadOS / iOS)与海外设计团队中,Craft(Craft.do) 凭借极致的原生渲染帧率、精致的文档排版与独特的“嵌套卡片(Nested Cards / Sub-pages)”体验吸引了大量早期拥趸。然而,随着个人知识库不断膨胀或团队规模突破 5 人进入跨部门协同阶段,许多用户逐渐发现 Craft 在复杂结构化数据管理、跨库关联聚合、API 自动化与 Windows/Android 跨端协作上存在明显瓶颈,最终选择将核心资产迁回 Notion。

在启动迁移或选型前,先通过架构矩阵厘清两者的底层差异(Notion 订阅与成本模型详见 Notion 版本选型与收费模式深度剖析):

对比维度 Notion(块引擎 + 关系型数据库) Craft(原生文档树 + Cards 卡片容器) 选型与迁移判断
底层组织哲学 一切皆块 + 跨库关系型数据库(Relation / Rollup) 树状文件夹 + 富文本页面 + 嵌套 Card 卡片 需要管理任务排期、CRM、OKR 与多维报表首选 Notion
结构化表格与公式 原生支持 Formula 2.0、map()/filter()、Sub-items 与图表 Tables 功能偏轻量文档表格,缺少跨表计算与自动化 重度数据运算与项目交付追踪必须使用 Notion
跨平台与离线体验 全平台一致(Web/Win/Mac/iOS/Android),支持离线缓存 macOS / iPadOS / iOS 原生 SwiftUI 极流畅,非苹果端偏弱 跨操作系统混合研发团队优先选择 Notion
协作权限与知识治理 支持 Teamspaces、权限组、Verified Pages 认证与审计日志 文件夹级共享与公开链接,缺少企业级复杂权限矩阵 中大型团队 SOP 与企业 Wiki 治理见 Notion 企业 Wiki 治理
自动化与开放生态 官方 REST API(2025-09-03)、原生 Automations 与 Webhook 开放 API 生态与第三方 SaaS 触发器覆盖有限 需要打通企微、飞书、GitHub 或 AI 管道选 Notion
视觉美感与写作手感 极简统一、支持自定义布局与双栏高转化排版 卡片阴影、渐变背景与媒体画廊开箱即美 迁移后可通过 Notion Callout、封面图与多栏布局还原视觉层级

二、无损迁移核心难点:Craft 嵌套卡片与内部双链的映射规范 #

与普通 Markdown 笔记工具不同,Craft 最大的迁移陷阱在于它独有的 Card(可点击钻取的嵌套子卡片)、Page Break(分页符) 与 .craft / .textbundle 打包格式。如果直接用普通单个 .md 导出再手动拖入 Notion,极易出现嵌套卡片被拍平、本地图片全部变成失效相对路径、craftdocs:// 内部链接断裂三大灾难。

在实施迁移前,建议遵循以下标准映射规范(Notion 数据库与双链架构范式见 数据库架构速查手册 与 Notion 双向链接架构实战):

Craft 原生元素 Notion 目标承载形态 转换规则与清洗注意事项
Space / Folder(空间与文件夹) Notion DB_Knowledge_Base 总库 + 分类 属性 切勿照搬多层物理文件夹,建议统一收口至总库并用 Select 标签重构目录
Document(顶层文档) Notion 数据库页面(Page Row) 提取文档标题、创建时间、Craft 原生 ID(写入 Source_Craft_ID 用于防重)
Nested Card(嵌套卡片) Notion 子页面(Sub-page)或 Callout 高亮块 卡片内含长文与二级结构时转为子页面;仅为短提示卡片时转为带图标的 Callout
Toggle / Folded Block Notion 原生 Toggle list 折叠块 Markdown 导出时若被展开为缩进列表,需通过脚本或正则恢复缩进层级
Internal @ / craftdocs:// Link Notion 页面引用或原生 Relation 关联 导出文本中的 craftdocs://open?blockId=... 必须通过标题映射表替换或挂载为关联
Images / PDF Attachments Notion Files & media 或图床外链 选择 TextBundle(.textbundle) 导出可完整保留 assets/ 文件夹内所有高清原图

三、实操步骤:从 Craft 导出清洗到 Notion API 批量迁入落地 #

第一步:在 Craft 执行最保真的全量导出(避开纯单文件 Markdown 陷阱) #

  1. Mac / iPad 端优先选择 TextBundle 或 Markdown (Folder) 导出:
    • 打开 Craft 目标 Folder 或全选文档 → 右键 Export As → 选择 TextBundle(或选择 Markdown 并勾选保留嵌套页面文件夹结构)。
    • 为什么不用 .craft 格式? .craft 是 Craft 专有打包文件,Notion 原生导入器无法解析;而 .textbundle 本质是一个包含 text.markdown 与 assets/ 图片子目录的标准开放包,能最大程度保真高清图片与 PDF 附件(本地导出与导入规范详见 数据导入 Notion 官方指南)。
  2. 清理本地附件与超限大文件:
    • 批量解包后检查 assets/ 目录下是否存在超过 5MB 的媒体文件(Notion 免费版单文件上传红线为 5MB,突破与图床托管方案见 Notion 文件上传限制突破实战)。

第二步:在 Notion 创建迁移承接数据库与质检字段 #

在 Notion 建立整页数据库 DB_Craft_Migration(行内库与整页库选型原则见 Notion 行内与整页数据库架构选型实战),至少包含以下核心属性:

  • 文档标题(Title)
  • Source_Craft_ID(Text:存放 Craft 原文件名或相对路径哈希,作为脚本幂等去重主键)
  • 原所属目录(Select:映射原 Craft Folder)
  • 原嵌套卡片数(Number:记录源文档包含的 Card/子页数量)
  • 残留断链数(Number:脚本正则扫描到的未替换 craftdocs:// 或本地无效图片路径数量)
  • 附件是否转存(Checkbox)
  • 迁移验收门禁(Formula 2.0:自动判定是否允许归档上线)

第三步:基于 Notion API 2025-09-03 的幂等批量迁入与断链扫描脚本 #

少量(50 篇以内)纯文本笔记可直接使用 Notion 左侧栏 Import -> Text & Markdown 导入;但面对数百篇带内部嵌套链接与附件的 Craft 文档,推荐通过 Node.js 调用 Notion API 2025-09-03 批量写入 data_source_id 并同步统计残留断链数(限流退避与 API 规范见 Notion API 速率限制与容错架构 与 Notion API 2025-09-03 迁移指南):

import fs from 'node:fs';
import path from 'node:path';
import { Client } from '@notionhq/client';

const notion = new Client({
  auth: process.env.NOTION_TOKEN,
  notionVersion: '2025-09-03'
});
const TARGET_DS_ID = process.env.NOTION_CRAFT_DS_ID;
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

// 检查是否已迁移,实现断点续传幂等性
async function existsByCraftId(craftId) {
  await sleep(350);
  const res = await notion.dataSources.query({
    data_source_id: TARGET_DS_ID,
    filter: { property: 'Source_Craft_ID', rich_text: { equals: craftId } },
    page_size: 1
  });
  return res.results.length > 0;
}

// 扫描 Markdown 正文中的断链与本地图片占位符
function analyzeMarkdown(rawMd) {
  const brokenCraftLinks = (rawMd.match(/craftdocs:\/\/[^\s)]+/g) || []).length;
  const localImgRefs = (rawMd.match(/!\[[^\]]*\]\((?!https?:\/\/)[^)]+\)/g) || []).length;
  const lines = rawMd
    .split('\n')
    .filter((line) => line.trim() !== '')
    .slice(0, 95); // 单次 create children 上限控制

  const children = lines.map((line) => ({
    object: 'block',
    type: 'paragraph',
    paragraph: { rich_text: [{ type: 'text', text: { content: line.slice(0, 1900) } }] }
  }));

  return { brokenCraftLinks, localImgRefs, children };
}

async function importCraftFolder(exportDir) {
  const files = fs.readdirSync(exportDir).filter((f) => f.endsWith('.md'));
  for (const file of files) {
    const craftId = file.replace(/\.md$/, '');
    if (await existsByCraftId(craftId)) {
      console.log(`跳过已导入文档: ${craftId}`);
      continue;
    }

    const rawMd = fs.readFileSync(path.join(exportDir, file), 'utf8');
    const { brokenCraftLinks, localImgRefs, children } = analyzeMarkdown(rawMd);

    await sleep(350);
    await notion.pages.create({
      parent: { data_source_id: TARGET_DS_ID },
      properties: {
        '文档标题': { title: [{ text: { content: craftId } }] },
        'Source_Craft_ID': { rich_text: [{ text: { content: craftId } }] },
        '原所属目录': { select: { name: 'Craft导入' } },
        '残留断链数': { number: brokenCraftLinks + localImgRefs },
        '附件是否转存': { checkbox: localImgRefs === 0 }
      },
      children
    });
    console.log(`已导入 ${craftId},检测到待修复链接/本地图片: ${brokenCraftLinks + localImgRefs}`);
  }
}

importCraftFolder('./craft-export').catch(console.error);

四、Formula 2.0 实战:自动化迁移完整性与断链验收门禁公式 #

数百篇文档迁入 Notion 后,人工逐篇核对图片与双链是否完整极易遗漏。在 DB_Craft_Migration 中添加 Formula 2.0 属性 迁移验收门禁,可实时计算全库迁移质量得分并精准拦截存在断链或未转存附件的问题页面(更多语法参见 Formula 2.0 速查手册):

lets(
  craftId, prop("Source_Craft_ID"),
  brokenCount, if(empty(prop("残留断链数")), 0, prop("残留断链数")),
  assetsReady, prop("附件是否转存"),
  cardCount, if(empty(prop("原嵌套卡片数")), 0, prop("原嵌套卡片数")),

  ifs(
    empty(craftId),
      style("⚪ 非迁移记录(缺少 Source_Craft_ID)", "gray"),
    brokenCount > 0 && !assetsReady,
      style("🔴 高危阻断 · 存在 " + brokenCount + " 处断链且本地附件未转存", "red", "bold", "red_background"),
    brokenCount > 0,
      style("🟠 需修补链接 · 发现 " + brokenCount + " 处 craftdocs:// 或失效路径", "orange", "bold", "yellow_background"),
    !assetsReady,
      style("🟡 待核对附件 · 请确认图片与 PDF 已上传至云端", "yellow", "bold"),
    cardCount > 0,
      style("🟢 验收通过 · 已完成 " + cardCount + " 个嵌套卡片结构对齐", "green", "bold", "green_background"),
    style("🟢 无损迁入验收通过", "green", "bold", "green_background")
  )
)

五、迁移后排版还原与常见问题排查(FAQ) #

  1. 为什么把 Craft 的多层文件夹全部导入后,在 Notion 侧边栏找不到熟悉的目录树?
    • Notion 的高阶效率哲学是“浅层侧边栏 + 数据库视图聚合”。与其建五层嵌套页面,不如把所有文档放进同一张 DB_Knowledge_Base,再按 原所属目录 创建多个预过滤视图(或使用 Notion 双向链接快速串联关联文章),亦可参考 Notion 与 Obsidian 深度架构对比与迁移实战 的知识资产复盘模式。
  2. Craft 里漂亮的居中大标题、卡片阴影和两栏并排效果如何在 Notion 中还原?
    • Notion 虽然不提供任意卡片阴影,但支持拖拽块生成最多 5 栏的多栏布局(Columns)、带自定义图标与底色的 Callout 高亮块,以及数据库详情页的自定义标签布局(详见 Notion 数据库自定义页面布局实战)。
  3. 导出后的文件夹在 Notion 批量导入时遇到乱码或图片丢失怎么办?

❓ 常见问题与答疑 (FAQ)

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

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