Notion Sync

核心功能

Notion Sync 是一套基于 Node.js 的命令行工具集，实现 Markdown 文件与 Notion 页面的双向同步，专为知识工作者和研发团队设计。

核心用法

双向同步引擎： 提供 md-to-notion.js 和 notion-to-md.js 两个核心脚本，支持将本地 Markdown 推送至 Notion（保留 H1-H3 标题、加粗/斜体、链接、列表、代码块等格式），也可将 Notion 页面内容拉取为 Markdown 文件。采用分批上传策略（每批 100 个 block）和 350ms 速率限制，适配 Notion API 的 ~3 req/s 限制。

数据库管理： 支持完整的数据库操作链路——search-notion.js 全局搜索、query-database.js 带过滤/排序的查询、update-page-properties.js 属性更新、add-to-database.js 将 Markdown 作为新页面插入数据库。涵盖 select、multi_select、checkbox、date、number 等常见属性类型。

变更监控： watch-notion.js 可持续监控 Notion 页面编辑状态，在 memory/notion-watch-state.json 中维护时间戳对比，输出 JSON 格式的变更检测结果，便于接入 CI/CD 或定时任务实现自动化同步。

安全凭证管理： v2.0 起废弃命令行明文 token，强制采用 --token-file（推荐，配合 chmod 600）、--token-stdin 管道输入或 NOTION_API_KEY 环境变量三种方式，避免凭证暴露于进程列表。

显著优点

• 零依赖部署： 仅使用 Node.js 内置模块（https、fs），无需 npm install，单文件即可运行
• 格式兼容性： 完整支持 Markdown 标准语法到 Notion block 的映射，代码块带语法高亮
• 协作工作流： 完美支持「本地编辑 → 推送 Notion → 多端协作 → 监控变更 → 拉取更新」的闭环
• 自动化友好： 所有脚本输出结构化 JSON，易于与 cron、GitHub Actions、Slack 通知等集成

潜在局限

• 属性填充限制： 数据库页面创建后，Type/Tags/Status 等属性需手动在 Notion UI 中设置，API 对 inline database 的属性更新支持不稳定
• 大文件性能： 超过 1000 个 block 的文件同步耗时较长（速率限制导致）
• 格式损失： 表格、深层嵌套列表（>3 级）转换可能存在偏差
• Node 版本要求： 需 v18+

适合人群

• 偏好本地 Markdown 编辑但需 Notion 云端协作的知识工作者
• 需要将研究/报告产出自动归档至 Notion 数据库的研发团队
• 构建文档自动化流水线（文档即代码 + Notion 发布）的技术写作者

常规风险

• API 速率限制： 高频操作可能触发 Notion API 限流，脚本虽有延迟策略但极端场景仍可能失败
• Token 泄露： 尽管 v2.0 强化了凭证管理，用户若自行硬编码 token 仍存在泄露风险
• 数据覆盖： 双向同步需配合变更监控谨慎使用，避免未预期的内容覆盖
• 归档误操作： delete-notion-page.js 实际执行 archive 而非永久删除，恢复需手动操作

核心用法

notion-sync 是一套基于 Node.js 的 Notion 双向同步工具集，无需 npm 依赖即可实现本地 Markdown 与 Notion 页面的互相同步。核心能力包括：

1. 双向内容同步：md-to-notion.js 将 Markdown 推送为 Notion 页面，支持标题、列表、代码块等完整格式转换；notion-to-md.js 反向拉取页面内容保存为 Markdown 文件。

2. 数据库操作：支持搜索工作空间、查询数据库（带过滤器和排序）、更新页面属性、获取数据库结构、将 Markdown 添加为数据库条目等完整 CRUD 能力。

3. 变更监控：watch-notion.js 持续追踪 Notion 页面编辑时间戳，与本地文件对比检测变更，支持自动化工作流集成。

显著优点：

• 零外部依赖：仅使用 Node.js 内置模块（https/fs/path），供应链攻击风险极低
• 安全凭证管理：Token 通过文件（推荐）、环境变量或 stdin 传入，v2.0 起已移除命令行明文参数
• 自动化友好：所有脚本输出 JSON，易于接入 CI/CD、cron 定时任务或通知系统
• 批量处理：自动限速（350ms/批次）和分块上传（100 blocks/请求），可处理大型文档

潜在缺点与局限性：

• 复杂 Markdown（表格、嵌套列表>3层）转换可能不完美
• 数据库属性需在 Notion UI 中手动设置，API 更新内联数据库属性偶有异常
• 超大型文件（>1000 blocks）同步耗时较长
• 变更监控基于轮询，非实时 webhook 推送

适合人群：

• 需要本地 Git 版本控制 + Notion 协作可见性混合工作流的开发者、研究者
• 希望自动化研究报告、新闻稿、会议笔记同步到 Notion 数据库的内容团队
• 需要将 Notion 作为 CMS 后端，但保留 Markdown 源文件备份的技术写作者

常规风险：

• T3 来源（个人开发者），虽代码历史干净，但缺乏企业级安全审计
• API Token 若文件权限设置不当（非 600）可能导致泄露
• Notion API 速率限制（~3 req/s）在批量操作时需等待
• 依赖 Notion 平台持续可用性及 API 兼容性