Markdown 与 Notion 双向同步神器

双向同步 Markdown 与 Notion 页面，支持数据库查询、属性批量更新及变更监控，适合协作编辑与项目管理场景。

基本信息

• 技能名称?Notion Sync
• 中文名称?Markdown 与 Notion 双向同步神器
• 作者?robansuini
• 分类?专业技能
• 版本?2.5.3
• 标签?notion, markdown, sync, database, project-management, collaboration, api, cli, automation

使用方法

使用说明
核心功能
Notion Sync 是一套基于 Node.js 的命令行工具集，实现本地 Markdown 文件与 Notion 工作空间的双向同步。核心能力包括：
双向同步 ： md-to-notion.js 将 Markdown 推送到 Notion（支持标题、列表、代码块等富文本）， notion-to-md.js 将页面内容拉回本地
数据库操作 ：查询数据库（支持复杂过滤与排序）、批量更新属性、添加 Markdown 为数据库新条目
变更监控 ： watch-notion.js 跟踪页面最后编辑时间，检测 Notion 端修改并输出 JSON 状态
安全设计 ：Token 支持文件、stdin、环境变量三种传递方式，避免命令行暴露凭证；文件操作默认限制在当前工作目录
显著优点

1. 零依赖部署 ：仅使用 Node.js 内置模块（https、fs），无需 npm install
2. 企业级安全 ：v2.0 移除 --token 明文参数，强制使用文件或环境变量；支持 --allow-unsafe-paths 显式覆盖路径限制
3. 自动化友好 ：全局 --json 标志输出结构化数据，便于集成 CI/CD 或 cron 任务
4. 速率限制处理 ：内置 300-350ms 延迟，自动适应 Notion API 限制（~3 req/s）
   局限性与风险
   属性创建限制 ：数据库页面的附加属性（Type、Tags、Status）需在 Notion UI 手动设置，API 对行内数据库的属性更新不稳定
   格式兼容性 ：复杂表格、三层以上嵌套列表转换可能不完美；超大文件（>1000 blocks）同步耗时较长
   仅支持归档 ： delete-notion-page.js 实际执行 archive 操作，非永久删除
   适合人群
   技术写作者：本地 Markdown 写作 + Notion 协作发布的工作流
   研发团队：将子代理生成的研究报告同步到 Notion 数据库追踪
   项目经理：批量更新任务状态、监控页面变更触发通知
   常规风险
   Token 泄露 ：若 ~/.notion-token 权限设置不当（建议 chmod 600 ），可能被同系统其他用户读取
   数据覆盖 ：双向同步存在冲突风险，建议配合 watch-notion.js 检测变更后再执行覆盖操作
   API 限流 ：大规模批量更新时仍可能触发 Notion 速率限制，导致操作中断