使用说明

核心用法

notion-api 是一个轻量级 Node.js CLI 封装器，用于与 Notion API 交互。主要功能包括：

1. 搜索：全局搜索 Notion 工作区内容
2. 数据库查询：支持指定数据源 ID 查询，可传入原生 JSON 过滤条件
3. 创建页面：在指定数据库中快速创建条目

认证支持 NOTION_KEY 环境变量或 ~/.config/notion/api_key 配置文件，实现密钥与代码分离，便于团队协作。

显著优点

零硬编码设计：数据库 ID 和密钥均通过参数或外部配置传入，代码仓库干净安全
JSON 原生支持：支持直接传入 Notion API 原生过滤和排序语法，灵活性高
轻量无依赖：单一脚本实现，Node 原生运行，无额外依赖负担
团队协作友好：密钥外置模式符合 12-Factor 应用原则

潜在局限性

功能覆盖有限：仅实现搜索、查询、创建三大核心操作，缺少更新、删除、块级操作等完整 CRUD
错误处理待完善：CLI 输出为原始 JSON，无格式化错误提示或重试机制
Rate Limit 需手动处理：仅文档提示限制，无内置限流或指数退避
无类型安全：纯 JS/Node 实现，缺少 TypeScript 类型校验

适合人群

需要快速集成 Notion 数据源的自动化脚本开发者
团队内部分享 Notion 工具链，需避免密钥泄露场景
熟悉 Notion API 原生语法、希望直接操作 JSON 的高级用户

常规风险

密钥管理：~/.config/notion/api_key 文件权限若配置不当可能导致密钥泄露
API 版本漂移：默认使用 2025-09-03 版本，Notion API 更新后可能产生兼容性问题
数据误操作：create-page 无预览确认机制，批量脚本需谨慎测试
依赖 Notion 集成权限：目标页面/数据库必须手动共享给集成，否则 API 调用返回 404 或 403

安全解读

核心用法

notion-api 是一个轻量级 Node.js CLI 工具，封装了 Notion 官方 REST API 的核心能力，支持三大功能场景：

1. 全局搜索：通过 search 命令在 Notion 工作空间内检索页面和数据库，支持分页控制
2. 数据库查询：通过 query 命令对指定数据库执行结构化查询，支持原始 JSON 过滤条件和排序
3. 页面创建：通过 create-page 命令向指定数据库新增条目，自动处理标题属性映射

身份认证通过 NOTION_KEY 环境变量或 ~/.config/notion/api_key 配置文件完成，符合"密钥不外泄"的安全原则。所有输出均为 JSON 格式，便于管道化处理和自动化集成。

显著优点

零依赖设计：不依赖任何 npm 第三方包，完全基于 Node.js 内置模块（fs/os/path/fetch），彻底消除供应链攻击风险
官方 API 直连：仅访问 api.notion.com 域名，HTTPS 加密传输，无数据中转或第三方服务介入
无硬编码密钥：凭证完全由用户配置，仓库内无任何敏感信息残留，符合安全共享要求
极简代码量：218 行代码实现完整功能，攻击面小，审计友好

潜在局限

输入验证薄弱：命令行参数缺乏类型检查和格式校验（如 Notion ID 的 UUID 格式），存在构造异常输入的风险
错误信息泄露：API 失败时可能将完整 URL（含数据库 ID 等敏感标识）输出至 stderr
无许可证声明：未指定开源许可证，用户使用权限不明确
无内置重试机制：依赖用户自行处理 Notion API 的速率限制

适合人群

需要将 Notion 纳入自动化工作流的开发者和技术团队
偏好轻量、可审计工具的安全敏感用户
已拥有 Notion Integration Token 的进阶用户

常规风险

凭证管理：Token 需妥善保管，避免提交至版本控制
数据范围：具备 Integration 权限的页面均可被访问，需仔细配置 Notion 端的页面共享范围
API 限制：受 Notion 官方速率限制（约 3 req/s），高频调用需自行实现退避策略
版本兼容性：默认使用 2025-09-03 API 版本，未来可能需要手动更新 NOTION_VERSION

notion api-client cli automation database productivity node-js integration

Notion API Tools 内容

scripts文件夹

手动下载zip · 3.2 kB

notion-api.mjstext/javascript

请选择文件