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

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

版本：1\.11\.0
npm 元数据更新时间：2026-11-11T02:35:07.423Z
中文译文更新时间：2026-11-11T09:48:20.252Z
软件包许可：MIT

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

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

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

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

## 中文简介

状态哨兵模拟器:SDK信封/存储/最小吞入、事件、问题、附件和确定性运输控制.

## 安装

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

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

## README

# @crvouga/嘲笑鸟-服务-哨兵

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

一个状态良好的哨兵SDK运输和事件/问题断言模拟器。 此初始软件包是 **阴道**数字 : 其受限表面遵循官方信封协议和中继响应,而不是整个 哨兵产品. 测试不需要供应商账户、集装箱、秘密或外出电话.

## 安装

```sh
bun add -d @crvouga/mockingbird-service-sentry
```

## 使用量

```ts
import * as Sentry from "@sentry/node"
import { DEFAULT_PROJECT } from "@crvouga/mockingbird-service-sentry"
import { createServer } from "@crvouga/mockingbird-service-sentry/server"

// Test setup: the emulator, and a DSN that points the Sentry SDK at it.
const server = await createServer()
const dsn = `${server.url.replace("://", `://${DEFAULT_PROJECT.publicKey}@`)}/1`

// The app's own Sentry calls.
Sentry.init({ dsn })
Sentry.captureMessage("Fixture failure", { fingerprint: ["fixture-group"] })
await Sentry.flush(2000)

// The test asserts on what the emulator captured.
const captured = await (await fetch(`${server.url}/__admin/events?project=1`)).json()
console.log(captured.events.length) // 1
await Sentry.close()
await server.close()
```

官员 `@sentry/nextjs` 财务报告和审定财务报表 `@sentry/node` SDKs都采用 DSN: 开始 `createServer()` 从 页:1 `/server` 条目和设置 `SENTRY_DSN` 改为 `http://<DEFAULT_PROJECT.publicKey>@127.0.0.1:<port>/1`,或 给它 `init`编号 :`NodeClient`。两个SDK在 **11.4.0 (中文(简体) )** (报告未提供标注版). 使用 SDK `flush()` 完成提交,然后 `POST /__admin/flush {"eventIds": […], "count": n}` 即时声明: `flushed: false` 意味着条件没有得到满足;它永远不会入睡.

REST请求的使用 `Authorization: Bearer fixture-rest-token`。 。 。 . `projects` 财务报告和审定财务报表 `restTokens` 选项 替换这些构造器固定装置。 每个项目包括组织、数字字符串、, 子弹,名字和32赫克的公用钥匙。 默认显然是合成的. 每个名称空间都收到 它自己的构造器固定装置,在重置时返回它们.

```sh
mockingbird-sentry serve --port 8810
```

## 路线和行为

-   `POST /api/{project}/envelope/`:字节精确的信封解析,隐含或明确长度, UTF-8 JSON 标题, 二进制附件, 未知项保留, 事件/ 交易/会话/ 届会/客户-报告项目。 Gzip/deflate请求压缩支持. 答复是: `200 {"id": "<event ID>"}` 当ID适用时,或 `200 {}` 用于会话/只报告信封.
-   `POST /api/{project}/store/`: JSON 事件摄取; 生成一个确定性的 32- hex 事件 ID 当缺席时。 遗产 `message: false` 被接受并被忽略,匹配中继日志 Entry; 原始 输入属性不能覆盖已规范的 REST 字段。 事件 ID 调试每个项目, 包括同时重试: 重播返回 同一ID,没有第二次抓取,发出计数或附件.
-   `POST /api/{project}/minidump/`: 原生小型水泵或多部分 `upload_file_minidump`选项 `sentry` JSON和额外的文件. 返回连字符事件 UUID 作为纯文本, 如 Relay . 验证 MDMP/PMDM 魔法并保留字节;原生崩溃符号不模拟.
-   `GET /api/0/projects/{organization}/{project}/events/`: 最新错误事件, 赤出数组, `full=true` 封顶一页为 10。 交易在细节和管理员搜索中仍然可用.
-   `GET /api/0/projects/{organization}/{project}/events/{event}/`:事件ID,消息/标题, 例外/套接字条目、上下文、面包屑、标签和固定用户身份.
-   `GET /api/0/projects/{organization}/{project}/issues/`: 光阵列组;默认为 `is:unresolved`, (中文(简体) ), `query=` 包括所有状态。 明确指纹优先;倒计时 分组是基于例外标题/框架,或配置时的信息.
-   `GET`编号 :`PUT /api/0/issues/{issue}/` 财务报告和审定财务报表 `/api/0/organizations/{organization}/issues/{issue}/`数字 : 读取或设定 `status` 改为 `unresolved`, (中文(简体) ), `resolved`,或 `ignored`解决一直持续到 明文状态更新; 自动回归检测在此初始模拟器之外.
-   `GET /api/0/projects/{organization}/{project}/events/{event}/attachments/` 财务报告和审定财务报表 `/{attachment}/`数字 : 附件元数据; `?download=1` 细节中将原字节返回给已认证的呼叫者.

读取页标使用 `limit` (1-100), (中文(简体) ), `cursor=0:<offset>:<previous flag>` 还有哨兵 `Link` 双向页眉 `rel="previous"` 财务报告和审定财务报表 `rel="next"`,其光标,以及 `results="true|false"`。 。 。 . 在走固定结果集时,稳定插入令可避免重复. 链接保存过滤器 和选定的命名空间,包括自定义管理员前缀。 模拟器支持发布/tag/跟踪 和状态过滤器;生产搜索语法、取样、趋势/排序和统计 没有默默表示为已执行的特征(见下文边界).

Ingest 认证接受 `X-Sentry-Auth: Sentry sentry_key=…, sentry_version=7`,查询 `sentry_key` 可选 `sentry_version`或自认证的 DSN 信封 相冲突页眉/平间 证书、 缺少认证、 密钥、 不兼容的协议版本、 错误的信封和 未知的项目密钥收到中继形状 `{"detail": "…"}` 错误。 没有发明的通用 API 错误代码或请求 ID: 摄取响应的 `id` 是供应商事件标识符。 准确 生产配额、过滤理由细节和REST 错误文本,超出文件记录的情况范围 约相相相. 默认有效载荷上限为20 MiB,可配置为 `maxPayloadBytes`。 。 。 .

## 测试控制

所有内部端点一起移动 `adminPrefix` (默认) `/__admin`) (中文(简体) ). 命名空间载体: `x-mockingbird-namespace`, (中文(简体) ), `/__admin/ns/<suite>/…`,或者 DSN 查询/标题证书和 REST 令牌 映射为 `PUT /__admin/credentials`。自认证的仅信封DSN使用信头/路径 命名空间; 证书映射无法在共享运行时间选择命名空间之前检查一个正文 . 时钟、重置、时间线检查站/检查站和快照别名、请求日记、计量、管理员 UI,收集回溯和通用缺陷是共享服务合同.

-   `GET /__admin/events?project=1&release=…&tag=key:value&trace=…`: 正常捕获错误和 交易。 所有列出的字段、时间戳、指纹、标记、上下文和面包屑都能活下来 须作修改; `user` 只保留假的固定符 `id`。 。 。 .
-   `GET /__admin/issues`: 将组与当前分辨率状态相匹配,使用相同的过滤器.
-   `GET /__admin/envelopes?project=1`: 项/标题元数据和拒绝标记; 永远不要生字节.
-   `GET`编号 :`PUT /__admin/settings`数字 : `grouping: "exception"|"message"`, (中文(简体) ), `sensitivePaths` (点路径; 默认 `request.data`, (中文(简体) ), `request.cookies`和 `rejectItems` (接受时丢弃的类型) 其他项目,含200个)。 这些是合成控制,而不是公共的哨兵设置 API.
-   `POST /__admin/flush {eventIds?, count?, project?}`:即时捕捉条件/结果.
-   `POST /__admin/issues/{id}/status {status}`: 解析/重新打开/空白.
-   `POST /__admin/projects/{id}/clear`: 清除项目的遥测,同时保留它的固定.

预设 : `rate_limited` (429个), `Retry-After: 60`, (中文(简体) ), `X-Sentry-Rate-Limits: 60:error:organization`, (中文(简体) ), `server_error` (503个), `network_reset` (口袋滴出)和 `item_rejected` (合成403过滤器). 每种都属于摄入范围,在写作前操作。 一般断层可以强迫其他5xx/429 回应。 官方的 SDK 测试证明错误类别配额在不阻断的情况下进一步降低错误 交易。 它立即验证行为,不重复睡眠.

### 原始抓取和编辑

授权/cookie和证书名字段进行回转过滤,包括页眉 双人 配置的敏感正体路径在正常数据进入存储之前被过滤或 供应商/管理人员诊断。 个人电子邮件,姓名和IP属性被删除. 日记/日志汇 仅包含请求的元数据和资源ID,从不包含正文,信头或附件字节. 保留原始线体和附件字节 **用 AES- GCM 加密** 在普通收藏中, 因此重置/时间线覆盖它们,而不通过一般的状态诊断披露平话. `runtime.instance(namespace).rawEnvelope(id)` 明确方案所有者获取原件 有线字节;它没有被管理员HTTP路由所暴露. 供应a `captureKey` 从 `createCaptureKey()` 当重开持久 SQLite 存储时; 默认密钥只活在那段运行时间的一生中 . 将这种明确的原始准入视为敏感的测试所有人准入。 正常事件/细节/搜索路径 返回已编辑的数据,而认证附件下载是一个明确的字节检索.

## 甲骨文证据

-   [官方信封语法和项目规则](https://develop.sentry.dev/sdk/foundations/envelopes/)。 。 。 .
-   [官方运输费率限额](https://develop.sentry.dev/sdk/foundations/transport/rate-limiting/)。 。 。 .
-   [正式页眉和光标示例](https://docs.sentry.io/api/pagination/)。 。 。 .
-   [项目活动清单](https://docs.sentry.io/api/events/list-a-projects-error-events/), (中文(简体) ), [项目问题清单](https://docs.sentry.io/api/events/list-a-projects-issues/) 财务报告和审定财务报表 [问题细节](https://docs.sentry.io/api/events/retrieve-an-issue/)。 。 。 .
-   [中继信封响应](https://github.com/getsentry/relay/blob/c4e9930349068039dd6ecd06cf338c527ee90165/relay-server/src/endpoints/envelope.rs), (中文(简体) ), [认证状态/消息](https://github.com/getsentry/relay/blob/c4e9930349068039dd6ecd06cf338c527ee90165/relay-server/src/extractors/request_meta.rs), (中文(简体) ), [最大误差、配额头和小型泵反应](https://github.com/getsentry/relay/blob/c4e9930349068039dd6ecd06cf338c527ee90165/relay-server/src/endpoints/common.rs)。 。 。 .
-   [转发遗留信息正常化](https://github.com/getsentry/relay/blob/c4e9930349068039dd6ecd06cf338c527ee90165/relay-event-schema/src/protocol/logentry.rs) 明确忽略 `message: false`;其CI所发现的种子被保留在回归登记册中.
-   官方 npm SDK 源代码 `@sentry/node`, (中文(简体) ), `@sentry/core` 财务报告和审定财务报表 `@sentry/nextjs` 11.4.0;已服务 测试使用实际客户端和运输,而不是SDK配额处理的再实施.

`bun run parity:service -- sentry` 需求 `SENTRY_API_URL`, (中文(简体) ), `SENTRY_AUTH_TOKEN`, (中文(简体) ), `SENTRY_ORGANIZATION_SLUG`, (中文(简体) ), `SENTRY_PROJECT_ID` 财务报告和审定财务报表 `SENTRY_PROJECT_SLUG`。跑者只比较 安全读取,永远不向现场销售商屈服。 测试不需要这些钥匙。 生活平等没有 ; 文档和 SDK 源是初始预言.

## 故意不模拟

供应商仪表板/帐单、完整的组织/项目/释放管理、生产配额、, 完整搜索 DSL 和搜索时间窗口, 排序模式, 而非最新/ 最后查看, 统计 系列/样本、源图/原生符号、会话汇总分析、剖析/重放, 完全崩溃堆放验证 遗留的压缩基质64 商店摄取 自动发行回归, 警告规则评价或可选问题提醒网点。 保留未知的信封项, 不 作为无支持产品特性处理。 组后退规则和强制过滤行为 明确的确定性测试政策,而不是哨兵的生产分组算法。 问题是: 由控制或供应商PUT明确解决/重新打开,绝不发明同步工人.

## API 密码

主要输入运行时间出口 : `SentryAPI` (单位:千美元)`fetch`, (中文(简体) ), `reset`, (中文(简体) ), `rawEnvelope`, (中文(简体) ), `captured`, (中文(简体) ), `issueWire`, (中文(简体) ), `sqlite`, (中文(简体) ), `state`, (中文(简体) ), `app`, (中文(简体) ), `createRuntime`, (中文(简体) ), `SENTRY_NAMESPACE`, (中文(简体) ), `SENTRY_PRESETS`, (中文(简体) ), `DEFAULT_PROJECT`, (中文(简体) ), `createCaptureKey`, (中文(简体) ), `sentryCredential`, (中文(简体) ), `document` 财务报告和审定财务报表 `supportedOperationIds`。 。 。 . 类型包括: `SentryAPIOptions`, (中文(简体) ), `SentryRuntime`, (中文(简体) ), `SentryRuntimeOptions`, (中文(简体) ), `ProjectFixture`, (中文(简体) ), `SentrySettings`, (中文(简体) ), `CapturedEvent`, (中文(简体) ), `CapturedEnvelope`,以及 `IssueRecord`。 。 。 . 服务器条目运行时间导出 : `createServer`, (中文(简体) ), `DEFAULT_PORT`, (中文(简体) ), `serveTarget`。服务器类型 : `SentryServer`, (中文(简体) ), `SentryServerOptions`。 。 。 . `createServer` 返回时 `{url, runtime, close, …}`; 关闭 每次测试后服务器。 CLI 条目运行 `serve` 带有常见的主机/端口/admin前置选项.

## 常见问题

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

状态哨兵模拟器:SDK信封/存储/最小吞入、事件、问题、附件和确定性运输控制\.

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

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

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

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

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

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

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

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

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

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

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

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