# @farm\.js/sentry 中文文档

规范地址：https://npmcn.com/package/%40farm.js/sentry/

版本：0\.1\.48
npm 元数据更新时间：2026-11-01T00:44:53.828Z
中文译文更新时间：2026-11-01T03:30:58.993Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40farm.js/sentry
原文对照：https://npmcn.com/package/%40farm.js/sentry/?lang=original
项目主页：https://github.com/farming-labs/farm.js#readme
源码仓库：https://github.com/farming-labs/farm.js

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

- 包体积（解压后）：32.8 kB，6 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：@sentry/node \>=8\.47\.0
- 首次发布：2026-08-28T14:36:43.067Z
- 最新版本发布：2026-11-01T00:44:53.660Z
- 已发布版本数：97（近 12 个月 97 个）

## 中文简介

为Farm.js提供错误报告和跟踪

## 安装

```sh
npm install @farm.js/sentry
```

也可以使用：`pnpm add @farm.js/sentry`、`yarn add @farm.js/sentry`、`bun add @farm.js/sentry`

## README

# @farm.js /哨兵

为Farm.js应用程序提供错误报告和跟踪。它映射了Farm的请求、渲染和 在Sentry上构建生命周期，这样错误就会随着路由上下文到达，请求也会被跟踪。

看到 [稳定性和支持](https://farmjs.dev/docs/stability) 因为这个包裹保证了什么。

## 安装

```bash
pnpm add @farm.js/sentry @sentry/node
```

`@sentry/node` 是可选的对等依赖项。如果一个 `dsn` 已配置且未安装， 插件记录一个明显的错误，并继续不报告，而不是阻止错误 从申请开始。

## 配置

```ts
import { defineConfig } from "@farm.js/core";
import { sentryPlugin } from "@farm.js/sentry";

export default defineConfig({
  plugins: [
    sentryPlugin({
      dsn: process.env.SENTRY_DSN,
      tracesSampleRate: 0.1,
      sourceMaps: true,
    }),
  ],
});
```

## 初始化早期

Node SDK在其他模块加载时给它们打补丁，因此它必须在其他模块之前运行 应用程序。为此添加一个检测文件：

```ts
// src/instrumentation.ts
import { registerSentry } from "@farm.js/sentry";

export const register = registerSentry({
  dsn: process.env.SENTRY_DSN,
  tracesSampleRate: 0.1,
});
```

没有这个插件仍然报告错误，但SDK的自动数据库和HTTP 仪器将无法连接。

## 它是做什么的

| 钩 | 行为 |
| --- | --- |
| `runtime.start` | 初始化SDK（如果还没有），并监听错误事件 |
| `runtime.context` | 按路由模式命名请求范围 |
| `runtime.after` | 设置响应的跨度状态 |
| `runtime.error` | 用路由、类型和请求上下文捕获异常 |
| `runtime.close` | 在关机时刷新挂起事件 |
| `build.configure` | 以下情况下启用源映射 `sourceMaps` 设置 |

span是通过路由模式而不是路径名来命名的，所以 `/users/[id]` 保持一个span名 而不是每个用户一个。

哪里SDK自己的HTTP工具已经为请求打开了一个跨度，插件 重命名其中一个，而不是启动另一个，因此自动HTTP和数据库范围保持嵌套 根据要求。它只在没有活动时创建一个span。

## Serverless

可以在没有关闭信号的情况下终止进程的主机永远不会运行 `runtime.close`,所以 挂起的事件丢失。而是在请求内部刷新：

```ts
sentryPlugin({
  dsn: process.env.SENTRY_DSN,
  flushOnResponse: true,
});
```

同花顺递给 `waitUntil`，因此主机将使调用保持活动状态，直到调用完成。

## 选项

| 选项 | 默认的 | 描述 |
| --- | --- | --- |
| `dsn` |  | 哨兵项目DSN。 |
| `environment` | 仪器模式 | 环境的名字。 |
| `release` |  | 部署的发布标识符。 |
| `tracesSampleRate` |  | 被跟踪请求的比例。总是发送错误。 |
| `sendDefaultPii` | `false` | 包括请求头和用户数据。 |
| `enabled` | `true` | 设置false注册钩子但不报告任何内容。 |
| `sdk` | `@sentry/node` | 使用SDK模块，而不是导入它。 |
| `flushOnResponse` | `false` | 在每次响应和请求失败后刷新。 |
| `flushTimeoutMs` | `2000` | 刷新超时。 |
| `sourceMaps` | `false` | 在生产构建中生成源映射。不上传，见下文。 |

`sendDefaultPii` 默认情况下关闭，因为错误事件可以携带请求标头和用户 数据。

## 源地图

`sourceMaps: true` 仅在生产构建期间生成源映射。它不上传 把它们传给哨兵，这样在地图被单独上传之前，生产堆栈的痕迹就会被最小化， 例如 `sentry-cli`． 尚未实现从构建中上传。

农场只有在源地图关闭时才会使用它的快速Oxc迷你车，这样它们才能移动 缩小到Nitro的简洁：

```bash
pnpm add -D @rollup/plugin-terser
```

如果没有它，生产构建就会失败 `Cannot find module '@rollup/plugin-terser'`.

## 运行时支持

节点预置。 `@sentry/node` 不运行在Cloudflare工人，需要什么 `@sentry/cloudflare` 相反,所以 `registerSentry` 不做手术吗 `edge` 和 `bun` 运行时。跟踪边缘支持 分开。

## 自带SDK

`sdk` 接受任何与插件使用的小结构接口相匹配的内容，这也是 如何对包进行单元测试：

```ts
import * as Sentry from "@sentry/node";

sentryPlugin({ sdk: Sentry });
```

## 常见问题

### @farm\.js/sentry 是什么？

为Farm\.js提供错误报告和跟踪

### 如何安装 @farm\.js/sentry？

在项目目录运行 npm install @farm\.js/sentry，或使用 pnpm add / yarn add / bun add。

### @farm\.js/sentry 支持 TypeScript 吗？

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

### @farm\.js/sentry 支持 ESM 还是 CommonJS？

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

### @farm\.js/sentry 可以商用吗？

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

### @farm\.js/sentry 还在维护吗？

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