核心用法
Notion Sync 是一套基于 Node.js 的 CLI 工具集，提供本地 Markdown 与 Notion 工作空间之间的双向同步能力。核心操作涵盖八大模块：
1. 搜索与查询 — search-notion.js 支持标题/内容检索，query-database.js 提供高级过滤与排序
2. 页面属性管理 — 单页更新（update-page-properties.js）与批量更新（batch-update.js）支持 select、multi_select、checkbox、date 等多种类型
3. Markdown ↔ Notion 同步 — md-to-notion.js 推送带格式的 Markdown（含代码高亮、列表、分隔线），notion-to-md.js 拉取并转换为本地文件
4. 变更监控 — watch-notion.js 检测页面编辑时间戳，输出 JSON 状态供自动化工作流集成
5. 数据库管理 — 添加条目、检视 schema、归档页面
显著优点
- 零依赖：仅使用 Node.js 内置模块（https、fs），无需 npm install
- 安全凭证管理：支持 token 文件、stdin 管道、环境变量三种方式，明确拒绝命令行裸传（v2.0 起
--token被移除） - 自动化友好：全局
--json标志确保 stdout 机器可读，stderr 用于进度日志 - 速率限制适配：内置 300-350ms 延迟，自动处理 Notion API 的 3 req/s 限制
- 批量处理能力：支持查询驱动或 stdin 传入 ID 的批量属性更新，带
--dry-run预览
局限性与潜在缺点
- 属性初始化限制：数据库页面创建后，Type、Tags、Status 等属性需手动在 Notion UI 补充，API 对 inline database 的属性写入存在稳定性问题
- 大文件性能：超过 1000 个 block 的 Markdown 因分批次上传+限速，可能耗时数分钟
- 格式兼容性：复杂表格、三级以上嵌套列表转换可能不完美
- 状态文件管理：
watch-notion.js默认使用相对路径memory/notion-watch-state.json，多工作目录场景需显式指定--state-file
适合人群
- 需要本地优先写作 + Notion 协作的创作者（如 newsletter 作者、技术写作者）
- 研究团队：本地生成报告后自动归档至 Notion 数据库，供成员标注元数据
- 项目经理：批量更新任务状态、监控页面变更触发 CI/CD 通知
- 隐私敏感用户：希望 token 不落盘进程列表、支持文件权限控制（chmod 600）
常规风险
- Token 泄露：虽支持安全传递方式，但用户仍可能误将
~/.notion-token提交至 Git - 误归档：
delete-notion-page.js实际执行 archive 而非永久删除，数据可恢复但需手动操作 - API 变更：Notion API 的速率限制或响应格式调整可能导致脚本异常，需关注上游更新
- 状态文件污染：未清理的
notion-watch-state.json可能在长期运行后累积过期页面记录