Notion 批量导出 Markdown / HTML / CSV 与无损迁移实战:从文件名 UUID 剥离、CSV 中文乱码修复到 Notion API 纯净导出与 Formula 2.0 归档门禁
一、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 样式) | 内部静态归档、法务审计留存、离线浏览器查阅 |
| 仅支持当前单页,无法批量导出子页面 | 解锁 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 读取数据库属性与页面块树,即可一步到位输出规范文件:
- 属性映射为 YAML Frontmatter:读取页面
properties中的Title、Slug、SEO 摘要与Last edited time,直接拼装成标准---头部元数据,省去人工补录标题与发布日期的步骤。 - 块级节点精准还原与媒体转存:遍历
blocks.children.list返回的段落、代码块(保留language字段)、callout高亮提示框与table表格;遇到image块且type === "file"时,在expiry_time到期前同步拉取二进制流写入本地images/<block_id>.webp并改写为相对路径。 - 增量同步降频控制:利用数据库过滤条件
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)
高频疑难解析与避坑指南完全不需要。绝大多数核心功能在免费 Free 计划中均可完整体验与实操练习,无需额外付费购买 Plus 或团队版。