Notion 批量导出 Markdown / HTML / CSV 与无损迁移实战:从文件名 UUID 剥离、CSV 中文乱码修复到 Notion API 纯净导出与 Formula 2.0 归档门禁

2026 年 11 月 19 日

一、Notion 原生导出格式全景对比与隐藏限制(别再盲目全选导出) #

无论是为了定期冷备份(参阅 备份你的数据)、将文档发布至 VuePress / Astro / Hexo 静态网站,还是把 Notion 数据库表交给财务人员用 Excel 分析,几乎所有用户都会用到右上角 ··· -> Export 功能。

但在真正动手前,必须先认清 Notion 四种原生导出方案的能力边界与套餐限制(官方操作入口参阅 导出为 Markdown、将数据库导出为 CSV 与 导出为 HTML):

导出格式 Free 免费版支持范围 付费版(Plus 及以上)增强 数据库与样式还原度 典型适用场景与致命痛点
Markdown & CSV 支持单页与有限层级;整库导出受限 支持勾选 Include subpages 全量导出 ZIP 正文转 .md,数据库转 .csv(含关系字段链接) 迁移至 Obsidian / Git 仓库;痛点:文件名带 32 位 Hex UUID、图链含 URL 编码
HTML 支持单页与基础嵌套导出 完整支持整套子树离线打包 还原度最高(保留 Toggle 折叠交互、多栏布局与 Callout 样式) 内部静态归档、法务审计留存、离线浏览器查阅
PDF 仅支持当前单页,无法批量导出子页面 解锁 Include subpages 批量合并/打包导出 适合打印(参阅 导出为 PDF) 对外报价单、合同定稿;痛点:长表格跨页易截断、无目录书签
API 编程导出 全套餐支持(需创建 Integration 并授权页面) 无导出体积限制,仅受 3 req/s 速率限制 可控度 100%(可自定义 YAML Frontmatter、下载图片并转存图床) 自动化 CI/CD 发布博客、企业增量冷备(参考 Notion API 自动化实战)

二、原生导出常见四大“翻车现场”与零代码应急修复 #

1. 用 Excel 双击打开导出的 CSV 中文全变成乱码 #

Notion 导出的 .csv 文件采用标准的 UTF-8(无 BOM) 编码,而 Windows 版 Microsoft Excel 默认按系统本地 ANSI(GBK)编码直接双击打开,导致中文标题与内容全部乱码。

  • 30 秒无损修复法(无需脚本):不要直接双击 .csv。新建一个空白 Excel 工作簿,依次点击顶部菜单 数据(Data)-> 获取数据(From Text/CSV),选中导出的 CSV 文件,在弹窗的 文件原始格式(File Origin) 下拉框中选择 65001: Unicode (UTF-8),点击“加载”即可 100% 正常显示中文。
  • Mac / Linux 批量加 BOM 命令行修复:如果需要将 CSV 直接发给业务同事双击打开,可为文件头部注入 \xEF\xBB\xBF(UTF-8 BOM 头):
    printf '\xEF\xBB\xBF' | cat - raw_export.csv > excel_ready.csv
    

2. 导出菜单里找不到 Export 按钮或迟迟收不到邮件 #

  • 按钮灰显或消失:联系工作区管理员检查 Settings -> Security & data,确认未开启 Disable export(禁止导出安全策略)。
  • 大体积 ZIP 异步邮件超时:当包含数千个子页面与高清附件时,Notion 会转为后台打包并通过邮件发送下载链接。建议按 Teamspace 或顶层模块分批勾选 Include subpages 导出,单次导出体积控制在 500MB 以内成功率最高。

三、工程化清洗脚本:一键剥离 ZIP 文件名 UUID 并修正 Markdown 图链 #

使用 Markdown & CSV 导出解压后,最大的工程痛点是每个文件夹和 .md 文件名末尾都会被强行拼接一段 32 位十六进制 ID(例如 项目周报 8f3a2c1b9e4d...md),且正文中引用的图片路径与内部链接全部指向这个带 ID 的路径,直接丢进静态博客(如 Notion 与 Astro 构建静态博客实战)或 Obsidian 双链工作流 时会导致链接大面积失效。

下面这段零第三方依赖的 Node.js 脚本可以安全地重命名所有目录与 .md 文件(去除 32 位 UUID 后缀),并同步重写正文里的相对路径与图片引用:

// clean-notion-export.mjs (Node.js 20+ 原生零依赖)
import fs from 'node:fs';
import path from 'node:path';

const EXPORT_DIR = process.argv[2] || './notion-export';
const UUID_SUFFIX_RE = /\s+[0-9a-f]{32}(?=\.[^.]+$|$)/i;
const renameMap = new Map(); // 记录旧编码路径片段 -> 清洗后名称

function collectAndRename(dirPath) {
  const entries = fs.readdirSync(dirPath, { withFileTypes: true });
  for (const entry of entries) {
    const oldFullPath = path.join(dirPath, entry.name);
    if (entry.isDirectory()) {
      collectAndRename(oldFullPath);
    }
    const cleanName = entry.name.replace(UUID_SUFFIX_RE, '');
    if (cleanName !== entry.name) {
      let targetPath = path.join(dirPath, cleanName);
      // 防止同名页面冲突覆盖,自动追加短序号
      if (fs.existsSync(targetPath)) {
        const ext = path.extname(cleanName);
        const base = path.basename(cleanName, ext);
        targetPath = path.join(dirPath, `${base}-${entry.name.slice(-6, -ext.length || undefined)}${ext}`);
      }
      fs.renameSync(oldFullPath, targetPath);
      renameMap.set(encodeURI(entry.name), encodeURI(path.basename(targetPath)));
      renameMap.set(entry.name, path.basename(targetPath));
    }
  }
}

function rewriteMarkdownLinks(dirPath) {
  for (const entry of fs.readdirSync(dirPath, { withFileTypes: true })) {
    const fullPath = path.join(dirPath, entry.name);
    if (entry.isDirectory()) {
      rewriteMarkdownLinks(fullPath);
    } else if (entry.name.endsWith('.md')) {
      let content = fs.readFileSync(fullPath, 'utf8');
      for (const [oldSeg, newSeg] of renameMap.entries()) {
        if (content.includes(oldSeg)) {
          content = content.split(oldSeg).join(newSeg);
        }
      }
      fs.writeFileSync(fullPath, content, 'utf8');
    }
  }
}

collectAndRename(EXPORT_DIR);
rewriteMarkdownLinks(EXPORT_DIR);
console.log(`导出目录清洗完成,共修正 ${renameMap.size / 2} 处 UUID 命名与相对链接。`);

重要提醒:如果 Notion 正文中包含直接粘贴自 Notion 私有桶的临时 S3 图片链接,链接在 1 小时后即会失效(详见 Notion 文件上传限制突破与图床防裂图实战)。若通过 API 自动化导出,建议在拉取 block.image.file.url 后立即将图片二进制流下载至本地 assets/ 或转存至 Cloudflare R2。

3.2 使用 Notion API 递归导出带 Frontmatter 的纯净 Markdown(替代手动点导出) #

对于需要持续把 Notion 文档同步到 Git 仓库、Hexo、Hugo 或 VuePress 的工程团队,手动下载 ZIP 再清洗仍然效率偏低。通过 @notionhq/client 读取数据库属性与页面块树,即可一步到位输出规范文件:

  1. 属性映射为 YAML Frontmatter:读取页面 properties 中的 Title、Slug、SEO 摘要 与 Last edited time,直接拼装成标准 --- 头部元数据,省去人工补录标题与发布日期的步骤。
  2. 块级节点精准还原与媒体转存:遍历 blocks.children.list 返回的段落、代码块(保留 language 字段)、callout 高亮提示框与 table 表格;遇到 image 块且 type === "file" 时,在 expiry_time 到期前同步拉取二进制流写入本地 images/<block_id>.webp 并改写为相对路径。
  3. 增量同步降频控制:利用数据库过滤条件 last_edited_time >= 上次归档时间 仅拉取发生变更的页面,并在每次 API 请求之间保持 350ms 间隔,避免触发官方 429 Rate Limit 限流。

四、Formula 2.0 知识资产“导出归档就绪度”门禁闭环 #

对于需要定期向 Git 仓库归档文档或对外发布独立站的内容团队,直接在 Notion 数据库中建立导出就绪度门禁,能在点击导出或触发 CI/CD 流水线前提前拦截脏数据(文本清洗技巧参阅 Notion 批量查找与替换实战指南):

数据库属性名称 类型 归档校验规则说明
Slug 英文别名 Text 必须符合 ^[a-z0-9]+(?:-[a-z0-9]+)*$,防止导出后 URL 含中文编码或空格
SEO 摘要 Text 建议控制在 60~160 字符区间,用于自动生成 Markdown Frontmatter description
含私有临时附件 Checkbox 标记正文中是否残留未转存外部图床的本地直传文件
归档状态 Select 草稿 / 待校验 / 允许导出
导出就绪度门禁 Formula 2.0 综合校验 Slug 合规性、摘要长度与附件状态,阻断不合格页面流入导出流水线

在 导出就绪度门禁 属性中填入以下 Formula 2.0 表达式(更多语法参见 Formula 2.0 速查手册):

lets(
  slug, prop("Slug 英文别名"),
  descLen, prop("SEO 摘要").length(),
  hasTempMedia, prop("含私有临时附件"),
  status, prop("归档状态"),
  validSlug, test(slug, "^[a-z0-9]+(?:-[a-z0-9]+)*$"),

  ifs(
    status == "允许导出" && hasTempMedia,
      style("🛑 阻断导出 · 存在未转存临时附件(S3 链接将过期)", "red", "bold", "red_background"),
    empty(slug) || !validSlug,
      style("🔴 Slug 不合规 · 仅允许小写字母数字与短横线", "red", "bold"),
    descLen < 30 || descLen > 180,
      style("🟡 摘要长度异常(" + descLen + " 字)· 建议 60~160 字", "orange", "bold", "yellow_background"),
    status != "允许导出",
      style("⚪ 尚未放行 · 请审核后切换为【允许导出】", "gray"),
    style("🟢 归档就绪 · 可安全导出纯净 Markdown/MDX", "green", "bold", "green_background")
  )
)

配合 Notion API 查询 归档状态 == "允许导出" 且门禁通过的记录,团队即可彻底摆脱手动点击 Export -> 解压 -> 改文件名 -> 修图链 的繁琐循环,实现知识资产的零损耗跨平台流通。

❓ 常见问题与答疑 (FAQ)

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

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