# @crvouga/mockingbird-service-notion 中文文档

规范地址：https://npmcn.com/package/%40crvouga/mockingbird-service-notion/

版本：1\.11\.0
npm 元数据更新时间：2026-11-11T02:24:37.541Z
中文译文更新时间：2026-11-11T06:29:23.666Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40crvouga/mockingbird-service-notion
原文对照：https://npmcn.com/package/%40crvouga/mockingbird-service-notion/?lang=original
项目主页：https://github.com/crvouga/mockingbird/tree/main/packages/service/notion#readme
源码仓库：https://github.com/crvouga/mockingbird

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：4.3 MB，18 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：2 个
- 首次发布：2026-10-05T09:27:22.627Z
- 最新版本发布：2026-11-11T02:24:37.190Z
- 近 30 天下载量：2880（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：22（近 12 个月 22 个）

## 中文简介

编号为2022-06-28 OAuth,数据库搜索和页面创建模拟器.

## 安装

```sh
npm install @crvouga/mockingbird-service-notion
```

也可以使用：`pnpm add @crvouga/mockingbird-service-notion`、`yarn add @crvouga/mockingbird-service-notion`、`bun add @crvouga/mockingbird-service-notion`

## README

# @crvouga/mockingbird-service-nodion (英语)

> 本地模拟器。 真正的API合同. 部分 [嘲笑鸟](https://github.com/crvouga/mockingbird)。 。 。 .

WIP 概念 **2022-06-28 (英语)** 数据库搜索、 OAuth 令牌交换、 数据库父页面创建和 街区儿童读取. 这是遗留数据库 API,而不是较新的数据源 API.

## 安装

```sh
bun add @crvouga/mockingbird-service-notion
```

## 使用量

```ts
import { Client } from "@notionhq/client"
import { createRuntime } from "@crvouga/mockingbird-service-notion"

// The app's own Notion client. Only its fetch changes: requests reach the
// emulator in this process instead of api.notion.com.
const emulator = createRuntime()
const notion = new Client({
  auth: "mock_notion_token",
  notionVersion: "2022-06-28",
  fetch: (url: string, init?: RequestInit) => emulator.fetch(new Request(url, init)),
})
const { results } = await notion.search({ filter: { property: "object", value: "database" }, page_size: 100 })
const [database] = results
if (database?.object === "database") console.log(database.properties)
```

该示例使用 `@notionhq/client@2.2.15`,这个API版本的SDK行. 运行 `mockingbird-notion serve --port 12127` 输入 `http://localhost:12127` 作为 消费者的API来源(SDK的) `baseUrl`) (中文(简体) ). 保留 `/v1` 在原始请求路径中。 没有通用供应商 此源代码覆盖的环境变量 。 所报告的整合使用原始取取法.

### 合同

-   `POST /v1/oauth/token`: HTTP 基本客户资格和JSON授权码赠款. 构造/ admin- seeded 代码绑定客户端, 重定向 URI 和工作空间授予 。 代码是 单用; 成功交换返回令牌、 机器人和工作空间元数据.
-   `POST /v1/search`: 领取者补助金加 `Notion-Version: 2022-06-28`. 回返遗产 `page_or_database` 列表中包含数据库 ids/propertys,查询过滤,页面大小, 启动 cursor, 下一个 cursor 有 more 。 成果仅限于授予的工作空间和 数据库编号。 Fixture 插入顺序是稳定的;相关性排名不是模拟的.
-   `POST /v1/pages`: 数据库 id 父和属性通过名称或id地址. 成功 以页 UUID 返回 200 并保留父/属性。 未知或无法进入 父母返回404;只读补助金返回403。 未知属性和错误值类型 返回 400 不写部分.
-   `GET /v1/blocks/{block_id}/children`: 返回一页内容的读取符(页 id 也是一页) block id; 连字符或32-hex ids 解析到同页)。 返回文件 `{object: "list", results, next_cursor, has_more, type: "block", block: {}}` 有种子的块 顺序; 每个块带 `id`, (中文(简体) ), `type`, (中文(简体) ), `has_children`, (中文(简体) ), `parent` (单位:千美元) `<type>` 对象 (单位:千美元)`rich_text[].plain_text`, (中文(简体) ), `to_do.checked`, (中文(简体) ), `code.language` 编号 : `code.caption[].plain_text`) (中文(简体) ). 一个街区 `has_children: true` 列出它的嵌入区块,从它自己的id,到任何深度. `page_size` 默认为100并封顶。 块形状是 **已核实文件** (单位:千美元)[https://developers.nodion.com/参考/get-block-儿童](https://developers.notion.com/reference/get-block-children)),没有甲骨文验证. **最好猜一猜,你猜怎么着, 未经甲骨文验证:** 不透明 `next_cursor` (最后返回的块的 id; 未知) `start_cursor` 实值 `400 validation_error`),准确的错误消息, `404 object_not_found` 用于 不明身份或补助金以外的页面, `400 validation_error` 用于非UUID标识,以及 `401` `unauthorized` 对于一个丢失或未知的标志。 429和5xx案件使用共享预设.

默认固定式是一个合成调查数据库(名称/标题、分数/号码),其编号为: `mock_notion_token`配置 `databases`, (中文(简体) ), `grants`, (中文(简体) ), `clients` 财务报告和审定财务报表 `codes` 其他费用 工作空间和 OAuth 方案。 此子集不需要授权浏览器或webhooks.

### 控件

`PUT /__admin/pages/{id}/blocks` 种子 一个页面的块树 从一个嵌入的轮廓,例如. `{"blocks": [{"type": "heading_1", "text": "FAQ"}, {"type": "toggle", "text": "Q", "children": [{"type": "code", "text": "x", "language": "bash", "caption": "c"}]}], "workspaceId"?, "title"?}`。 。 。 . 类型 : `paragraph`, (中文(简体) ), `heading_1..3`, (中文(简体) ), `bulleted_list_item`, (中文(简体) ), `numbered_list_item`, (中文(简体) ), `to_do` (单位:千美元)`checked`, (中文(简体) ), `toggle`, (中文(简体) ), `quote`, (中文(简体) ), `callout`, (中文(简体) ), `code` (单位:千美元)`language`, (中文(简体) ), `caption`, (中文(简体) ), `divider`。模拟器将扩展 将缩放为逗号的块形状, 并替换该页上任何较早的树; 未知的 id 变为一个 独立页面。 整个大纲首先被验证:一个问题是 `400` 什么都没有储存. 块通过 API 写入( B)`PATCH`,更新,删除)不是模拟.

共享 `/__admin/state/{databases,grants,clients,codes,pages}` 表面种子并检查记录. 重置还原了构造器固定装置并清除所创建的页面。 共享时间线、时钟、日记 和错误 API 应用;日志不包含页面内容或证书。 只使用合成数据. 命名空间由标题选择, `/__admin/ns/{name}` 前缀或映射的无记名符号. 设定 `adminPrefix` 以移动控件.

预设 : `unauthorized`, (中文(简体) ), `rate_limited` (429,重试后), `server_error` (503个) `connection_drop`共同过失规则支持延迟和一发一发失败.

接收测试涵盖通过原始取取取、OAuth绑定/重放、计划出错的第284期, pagination,隔离/重置,日记编辑并服务HTTP. 全部进行财产测试 三次行动并探测出差异. `bun scripts/parity.ts` 需求 `NOTION_API_KEY`· ; 它只检查一个被绑定的版本的空搜索,从不创建真实的页面. 生活平等还没有实现. 官方SDK v2.2.15类型提供了存档的有线合同证据.

### 故意不模拟

新的数据源 API, 完整的丰富文本渲染/注释, 块写( 读取和管理员种子存在), 超出以上列表的块类型, 数据库编辑/ query, 页面母创建,关联排序,完整页面/数据库响应元数据,公式, 卷起、选择选项的创建、关系解决和供应商外地的充分限制. 属性验证检查请求的 schema 的值类型: 标题/ 文本、 数字、 复选框、, 可失效的字符串/日期,选择/状态/多选择,人/关系代号和文件对象. 它没有模仿每个Notion属性限制或将打出的请求值扩展至完整的响应对象. 只有被绑定的API版本被接受.

## API 密码

-   `NotionAPI`: 用 `fetch`, (中文(简体) ), `reset` 数据库/赠款/客户/编码/页面收藏.
-   `createRuntime`:共享管理员,名空间,时钟,断层和日记合同.
-   `NOTION_NAMESPACE`:服务名.
-   `NOTION_PRESETS`:确定断层预设.
-   `DEFAULT_DATABASES`:合成调查计划.
-   `BLOCK_TYPES`: 管理区块大纲接受的区块类型.
-   `document`, (中文(简体) ), `operationIds`, (中文(简体) ), `supportedOperationIds`: 生成了 OpenAPI 元数据.
-   `createServer`, (中文(简体) ), `serveTarget`, (中文(简体) ), `DEFAULT_PORT` 从 `./server`:节点HTTP/CLI目标 (默认端口12127).

公共类型 : `Property`, (中文(简体) ), `Database`, (中文(简体) ), `Grant`, (中文(简体) ), `OAuthCode`, (中文(简体) ), `Client`, (中文(简体) ), `Page`, (中文(简体) ), `NotionAPIOptions`, (中文(简体) ), `OperationId`, (中文(简体) ), `SupportedOperationId`。 。 。 .

## 常见问题

### @crvouga/mockingbird-service-notion 是什么？

编号为2022-06-28 OAuth,数据库搜索和页面创建模拟器\.

### 如何安装 @crvouga/mockingbird-service-notion？

在项目目录运行 npm install @crvouga/mockingbird-service-notion，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 mockingbird-notion，可以用 npx mockingbird-notion 直接运行。

### @crvouga/mockingbird-service-notion 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @crvouga/mockingbird-service-notion 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @crvouga/mockingbird-service-notion 可以商用吗？

@crvouga/mockingbird-service-notion 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @crvouga/mockingbird-service-notion 的下载量有多少？

根据 npm 官方下载统计，@crvouga/mockingbird-service-notion 在 2026/10/11 – 2026/11/09 这 30 天内被下载 2,880 次，日均约 96 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @crvouga/mockingbird-service-notion 还在维护吗？

最新版本 1\.11\.0 发布于 2026/11/11（今天）；至今共发布 22 个版本，其中过去 12 个月发布了 22 个；首次发布于 2026/10/05。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。