# @alwaysmeticulous/backend-recorder-workerd 中文文档

规范地址：https://npmcn.com/package/%40alwaysmeticulous/backend-recorder-workerd/

版本：3\.6\.0
npm 元数据更新时间：2026-11-05T16:24:56.263Z
中文译文更新时间：2026-11-05T23:10:30.126Z
软件包许可：ISC

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

原始 npm 页面：https://www.npmjs.com/package/%40alwaysmeticulous/backend-recorder-workerd
原文对照：https://npmcn.com/package/%40alwaysmeticulous/backend-recorder-workerd/?lang=original
项目主页：https://github.com/alwaysmeticulous/meticulous-sdk
源码仓库：https://github.com/alwaysmeticulous/meticulous-sdk

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

- 包体积（解压后）：1.4 MB，120 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.19\.0
- 运行依赖：0 个
- 首次发布：2026-07-27T17:09:40.883Z
- 最新版本发布：2026-11-05T16:24:55.741Z
- 近 30 天下载量：121774（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：25（近 12 个月 25 个）

## 中文简介

Cloudflare Workers(工人)的默契后端记录器 shim. HTTP在开发记录期间向当地的Meticulous记录器侧车报告进出的捕获事件.

## 安装

```sh
npm install @alwaysmeticulous/backend-recorder-workerd
```

也可以使用：`pnpm add @alwaysmeticulous/backend-recorder-workerd`、`yarn add @alwaysmeticulous/backend-recorder-workerd`、`bun add @alwaysmeticulous/backend-recorder-workerd`

## README

# Cloudflare工人(工人)的默特化后端记录器

当地开发期间录制Cloudflare工人的后端会话的在职者shim(`wrangler dev`页:1 **已部署** 工人或网页项目。 它报告工人的入境请求,离开 `fetch` 调用(包括请求/答复机构,封顶为256 KB),绑定和 KV 调用和postgres.js 查询作为捕捉事件到一个Meticulous recorder sidecar,它将它们变成后端会话录音.

Shim是被动的:向外请求直接前往其真实目的地;侧车从不在请求路径上,无法到达的侧车或任何抓取失败都不会影响你的应用.

侧车住的地方是两个设置的唯一区别:

|  | 侧车 | 配置由 |
| --- | --- | --- |
| `wrangler dev` | 地方进程`npx @alwaysmeticulous/cli record backend`(中文(简体) ) | 页:1 `METICULOUS_SIDECAR_URL` var. (中文(简体) ) |
| 已部署(`wrangler deploy`, (中文(简体) ), `wrangler pages deploy`,预览) | [`@alwaysmeticulous/backend-recorder-sidecar-worker`](https://www.npmjs.com/package/@alwaysmeticulous/backend-recorder-sidecar-worker),部署在您的 Cloudflare 账户 | (单位:千美元) `METICULOUS_SIDECAR` 服务绑定 |

## 地方发展的设置

1.  安装 shim :
    
    ```bash
    npm install @alwaysmeticulous/backend-recorder-workerd
    ```
    
2.  包装您的 ES 模块操作器 :
    
    ```ts
    import { withMeticulous } from "@alwaysmeticulous/backend-recorder-workerd";
    
    export default withMeticulous({
      async fetch(request, env, ctx) {
        // your app
      },
    });
    ```
    
3.  启用 `nodejs_als` (或 `nodejs_compat`) 相容性旗帜 `wrangler.toml`数字 :
    
    ```toml
    compatibility_flags = ["nodejs_als"]
    ```
    
4.  通过 Meticulous CLI 运行您的 dev 命令, 启动记录器侧车并将其 URL 传递到 `wrangler dev` 自动 :
    
    ```bash
    npx @alwaysmeticulous/cli record backend -- npx wrangler dev
    ```
    
    如果记录器不能启动——没有证书,没有网络来取取侧车捆,一个无法使用的端口——CLI会警告和运行你的dev命令没有记录而不是失败,所以这可以安全地离开 `dev` 剧本.
    
    或者单独运行侧车 `npx @alwaysmeticulous/cli record backend` 并将其指向自己——值必须是工人的var/约束(在工人内部看不到主环境变量),例如: `.dev.vars`数字 :
    
    ```
    METICULOUS_SIDECAR_URL=http://127.0.0.1:9670
    ```
    
    或者说 `wrangler dev --var METICULOUS_SIDECAR_URL:http://127.0.0.1:9670`。 。 。 .
    

没有安装了副车厢的包装是完全的通过,所以安全地用部署的代码离开.

## 已部署的工人或页面项目的设置

1.  将副车开进你的Cloudflare账户,跟着 [`@alwaysmeticulous/backend-recorder-sidecar-worker`](https://www.npmjs.com/package/@alwaysmeticulous/backend-recorder-sidecar-worker) 读取。 这是一个文件和一个 `wrangler deploy`。 。 。 .
    
2.  在您想要录制的每一个环境中, 添加一个对您的应用程序绑定的服务 :
    
    ```toml
    [[services]]
    binding = "METICULOUS_SIDECAR"
    service = "meticulous-recorder-sidecar"
    ```
    
3.  包好你的处理器 对于一个ES模块工人,即 `withMeticulous`,如上. (中文(简体) ). 对a **云旗页** 项目,工人出口 `onRequest` 而不是说 `{ fetch }`,使用时 `withMeticulousPagesFunction`数字 :
    
    ```ts
    import { withMeticulousPagesFunction } from "@alwaysmeticulous/backend-recorder-workerd";
    
    export const onRequest = withMeticulousPagesFunction(handler);
    ```
    
    应用它 **最外侧**在你自己的包装 重新写之前 `context.env`:记录器在 `env` 所以先用包装来代替自己的外表 就能掩盖真实的情况.
    
4.  如果你的应用程序询问 Postgres —— 超过超驱动程序, 请说 —— 把客户端交给我们, 这样它的询问也会被记录下来 。 在工人中没有自动补丁的接合 : `postgres` 在建设时被嵌入你的捆绑 并且从来没有通过一个模块加载器.
    
    ```ts
    import { withMeticulousPostgres } from "@alwaysmeticulous/backend-recorder-workerd";
    
    const sql = withMeticulousPostgres(
      postgres(env.HYPERDRIVE.connectionString),
    );
    ```
    
    一个呼叫覆盖了隔离区中的每个客户端,它会返回客户端不变. 如果有其它东西也包住客户端, 应用最外侧( Sentry's) `instrumentPostgresJsSql`,一个伐木代理).
    

环境之间没有什么需要改变的:包装器在它找到的侧车上激活,而配置两个侧车都是通过. 绑定胜负 `METICULOUS_SIDECAR_URL` 当两者同时存在时,因为只有绑定才能被故意添加到部署的wrangler配置中.

一个请求的捕获事件 被分批到 **一个** 页:1 `ctx.waitUntil` 在你的答复散去之后——所以,要求打二十通电话需要一次往返,而不是二十通.

## 捕捉到的东西

-   **入境请求** (方法、 URL、 页眉、 状态; 没有机构),通过 `x-meticulous-session-id` 由Meticulous前端记录器所盖的页眉——或者,对于页面的初始导航,通过id shim mints本身(见 [第一页渲染的会话 ID](https://npmcn.com/package/%40alwaysmeticulous/backend-recorder-workerd/#readme-session-ids-for-the-first-page-render)) (中文(简体) ).
-   **发送 `fetch` 电话** 在处理输入请求时作出:方法、 URL、 标题、 状态和请求/ 响应机构( UTF-8, 上限为 1 MB; 长寿命流如 SSE 被截取) .
-   **呼叫通过 `fetch`\- 形状装订** ——服务装订和持久对象活字根——记录如出发取来,外加 `env` 键入了电话。 不需要更改代码: 绑定 `fetch` 无论应用程序从哪里读到,包括通过 `cloudflare:workers` 而不是处理器的 `env` 参数.
-   **KV 命名空间操作** —— 说 `get`, (中文(简体) ), `getWithMetadata`, (中文(简体) ), `put`, (中文(简体) ), `delete` 财务报告和审定财务报表 `list` 名称空间 `env`,用绑定名称、密钥、调用参数和值记录为JSON(所以 `JSON.parse` 重构应用程序所见所闻 `type` (请阅读)。 也不需要更改代码。 一个作为流读取的值从未被记录器读取过——它将从应用中取出字节——而二进制值被跳过;两个大小写都用理由而不是值来记录.
-   **postgres.js 查询**当您申请时 `withMeticulousPostgres` (见上文):SQL与 `$1`\-样式占位符,插入参数,行会塑造所要求的查询,以及解析出行——或出错,所以一个查询,合法失败的重放是同一个失败而不是一个缺口. 诅咒, `.forEach()`,COPY流和 `.describe()` 未经记录,因为他们没有结果.

## 第一页渲染的会话 ID

浏览器不能将自定义头头放入顶级导航上,在开始一个会话的导航上,前端记录器还没有刻出一个ID——只有HTML到达并片段运行之后,才有. 因此,生成您的服务器侧渲染的请求是无法到达的被标记的请求,以及它所做的一切(渲染是自己的) `fetch` 将完全不记录任何会议.

Shim关闭了另一端的缺口: 对于这样的要求 **薄荷会议本身 id**,记录下的全部请求,并发布到页面上,页面采纳了它而不是自己磨. 然后整个页面加载在一个会话id下.

**当作薄荷.** 仅用于一个浏览器装入页面的合理内容: a `GET`编号 :`HEAD` 与 `Sec-Fetch-Dest: document`, (中文(简体) ), `iframe` 或者说 `frame` (或,如果没有该标题,则 `Accept` 包含 `text/html`(没有入境) `x-meticulous-session-id`内页 `fetch`一个RSC导航,一个健康检查和一个爬行器都下降。 它只在录音时发生, 所以一个部署的工人,没有配置的侧车是未受伤害的.

包含一个子帧是因为它不可靠地折叠到上帧的会话中:前端记录器将子帧的数据转发到上帧并压制自己的会话,只有在上帧在同一同物下录入时,所以其父无记录器的跨出源帧本身就是会话——它的渲染需要的id和上层一样多. 子框架在哪里 _已经_ 等待,任何事物都不采用身份标识,任何身份标识都不采用,成本也不高: `meticulous.session_id_origin: "backend"`,摄入量则算不上一个会议没有被采用为无印记而非邮票.

**页面如何学习.** 两个渠道,要么足够:

1.  `Server-Timing: metsession;desc="<id>"` 回应。 录音机从 `performance.getEntriesByType("navigation")[0].serverTiming` ——文档本身的脚本可以读取的一个响应头,它持续了文档的一生,因此不管片段负载晚于何时,这都有效. **不需要更改应用程序 .** 限于安全上下文,而缓存或代理可能会剥取.
2.  你的应用程序通过 `getMeticulousSessionId()` - 通常为: `data-session-id` 在录音机自己 `<script>` 标记 (`window.METICULOUS_SESSION_ID` (见E/CN.4/Sub.2/2003/L.31)。 精准并免疫于头部缓冲;花费一行.

```ts
import {
  getMeticulousSessionId,
  withMeticulous,
} from "@alwaysmeticulous/backend-recorder-workerd";

export default withMeticulous({
  async fetch() {
    const sessionId = getMeticulousSessionId();
    return new Response(
      `<script src="/recorder.js" data-session-id="${escapeHtml(sessionId ?? "")}"></script>`,
      { headers: { "content-type": "text/html" } },
    );
  },
});
```

随你如何去掉它,因为你将插入标记:在文件导航上,它是我们自己的薄荷标识,但在任何其他请求下,则是输入页头的逐字记录.

无论是哪种方式,记录器只采用 id,而它的薄荷时间是 **现在60多岁左右, 无论是哪个方向** (会议IDs嵌入了他们的薄荷时间). 这种束缚使得CDN或浏览器缓存的响应无法向每个接收它的访客发送一个会话ID. 在窗口内,分享仍然是可能的,所以 **hTML 可缓存的应用程序尚不是好候选人** - 关掉薄荷:

```ts
export default withMeticulous(handler, { mintProvisionalSessionIds: false });
```

或设置 `METICULOUS_BACKEND_PROVISIONAL_SESSION_IDS` var 改为 `"false"` (一个工人 var/捆绑,像 `METICULOUS_SIDECAR_URL` ——主机环境变量在工人内部不可见.

`getMeticulousSessionId()` 也正是id如何到达另一个过程. 文档导航没有入境信头可供您的应用程序转发,因此,一个向自己的服务提供粉丝的工人必须将ID传递给 `x-meticulous-session-id` 本身;shim不会把它添加到外出的请求中.

请求机构有秘密的JSON领域(`clientSecret`, (中文(简体) ), `apiKey`, (中文(简体) ), `token`, (中文(简体) ), `password`,)替换为 `REDACTED` 在他们离开工人之前,因为大量的API在身体中携带证书而不是头像. 反应机构是逐字存储的:当它们为UTF-8时作为文本,否则则作为基准64(标记如下: `http.response.body.encoding: "base64"`),因此一个二进制响应,如存档或图像重放字节来表示. 一个KV `put` 数值以同样的方式被编辑,原因相同; 从 KV 读取的值是逐字存储的, 像响应体一样 .

## 重播

当Meticulous对您的应用程序重放一个会话时, 同样的包装器为回放录音服务: 已退出 `fetch` 电话是从录音中回答的, 而不是到达真正的服务, 时钟被冻结 在录制的会话结束时 `Math.random` 编号 : `crypto.randomUUID` 编号 : `crypto.getRandomValues` 在每次重播时 应用薄荷都是一样的 重放由"Meticulous"重放跑者注射器头激活,因此不需要额外来启用.

重放为 **隐形**: 录音不覆盖的调用失败 `[backend-recorder] workerd replay: …` 错误而不是悄悄地到达了真正的服务,所以录制中的一个漏洞会浮出水面,而不是将回放变成活的流量. 对于一个在重播时必须保持直播的电话,设置 `meticulous-passthrough` 页眉到 `true` 应请求:

```ts
await fetch(url, { headers: { "meticulous-passthrough": "true" } });
```

在服务回放时,shim 前缀请求-scoped `console.debug`, (中文(简体) ), `console.log`, (中文(简体) ), `console.info`, (中文(简体) ), `console.warn`, (中文(简体) ), `console.error`,以及 `console.trace` 输出与活动重放 身份证 每个请求都从 `AsyncLocalStorage`,所以日志在 一个工人隔离服务 同时重复播放。 启动和重放请求之外的其他工作 没有标记.

通过绑定和KV命名空间的呼叫从录音(参见限制)中得不到服务,并且永远不会失败——它们总是达到真正的绑定.

## 特工群测试

第三个模式坐落在Meticulous驱动运行(代理会话生成)的重放旁. 它在两个部署舱启动, `METICULOUS_AGENT_SWARM_TESTING_SIDECAR_URL` 财务报告和审定财务报表 `METICULOUS_AGENT_SWARM_TESTING_RUN_ID`,由谁部署工人来进行群跑;URL的验证方式与回放侧车URL一样. 每个出 `fetch` 向拦截者提供URL名称的呼叫服务:拦截者要么提供响应服务,要么通过呼叫传递到真正的服务.

模式通过设计来达到最佳效果——与回放的母调相反. 截取器的呼叫无法回答(漏接,无法接通或行为不当的截取器,shim无法代表的响应)永远不会失败;它只是到达了真正的服务. 没有被冻结的时钟, 没有播种的随机性和记录。 这个 `meticulous-passthrough` 信头跳过截取器完全用于呼叫.

## 代码覆盖

Meticulous 可以报告您服务器行中的哪一行被执行的重放会话 。 工人没有可使用的V8覆盖范围——其检查员从未派遣 `Profiler.enable`这样 `Profiler.startPreciseCoverage` 无法获取,而一个覆盖则称它做转发报告二进制计数,永不重置,不能按请求拆分。 因此线路被标记在建设时间取而代之.

将插件添加到构建中 **上传测试**而不是你部署的那个

```ts
import { defineConfig } from "vite";
import { meticulousCoverage } from "@alwaysmeticulous/backend-recorder-workerd/vite";

export default defineConfig({
  plugins: [meticulousCoverage()],
});
```

然后回放报告覆盖度自动——包装器将每个请求所运行的行数张贴到Meticulous回放侧式车上,后一回放将它归为会话.

-   仅 **服务器** 模块是仪器; 除非您通过, 客户端构建是未受影响的 `includeClient: true`。 。 。 .
-   `node_modules` 和虚拟模块总是被跳过. `exclude: [/pattern/]` 跳过更多.
-   被乐器捆绑可以安全地用覆盖来运行:在无物收集时,每个标记都是不开放的,所以同样的图像仍然适用于普通回放和本地开发.
-   插件无法解析的模块不会被修改 。 覆盖是永远不会值得 失败你的建设.
-   有些行是故意不标记的,因为标记它们将意味着重写代码而不是添加到其中:模块上层的语句(它们在孤立启动时运行,在任何请求之外),类 `static` 块,例如 `if (x) return;`,和条件 `else if` (只有第一个) `if` 虽然每个分支机构仍然有自己的标志 因此,即使在执行这些命令的跑道中,这些行也是被揭穿的.

报告行号是来源中的行,不是捆绑中的行. 该插件运行在您所建的 TypeScript/JSX 通过之后,它会重新打印出每个模块,并放下注释和空白行——因此它会解决每行通过该通过源图返回. 有两个后果值得了解:

-   您构建的源图未生成的模块仍然是仪器, 但其行被报告为构建打印 。 插件表示在构建的结尾会影响多少模块.
-   一个模块,其源映射覆盖了其它一些文件,却被完全跳过,而不是对照错误的行报告.

因为每个函数都会重新读取当前请求的槽,所以一个比创建它的请求活取的回调被贷记到实际运行它的请求,而不是构建它的请求.

## 限制

-   流化反应被截取出:当处理器返回时报告入行请求,对于流化反应,在流化结束前报告出行请求,出行机构上限为1 MB. 其主要终点为SSE的应用程序不会忠实地记录.
-   约束之外的其他 `fetch`\- 形状的和 KV 命名空间没有被捕获: D1, R2, 队列, RPC 方法调用一个命名的切入点(`env.SVC.someMethod()`)——RPC方法并非可补丁属性,因此无法以这种方式被截取.
-   非文本的 KV 值不记录其值: 读取 a `stream` 将字节从应用程序中取出,二进制值被跳过,因为 KV blobs 很大而不是 UTF-8 。 操作、密钥和论据仍被记录下来 `omitted` 说它是哪种情况.
-   违约时跳过资产约束(`ASSETS`, (中文(简体) ), `__STATIC_CONTENT`:资产字节为大并常为二进制,资产服务通常是工人最高量的调用. 使用 `options.skipBindings` 跳过别人.
-   出关 `fetch` 向一个数据犬代理,没有前端会话ID,被记录为一无所有. 追踪器在自己的定时器上冲出,所以没有任何东西能将呼叫归为属性,而有效载荷就是它缓冲过的每一个跨度. 目的地只有在其端口为 `8126` **财务报告和审定财务报表** 它的路径是代理商自己的 API 端点之一(`/info`, (中文(简体) ), `/v0.4/traces` 还有那个家庭的其他成员, `/profiling/v1/input`, (中文(简体) ), `/telemetry/proxy/…`, (中文(简体) ), `/evp_proxy/…`因为8126和826的应用软件 可能会为任何东西服务 `/v0.4/traces`\- 其它地方的形状路径是应用程序自己的终点。 无代理顺从于 a `datadoghq.com` 收录内容不涵盖在内,也没有发出通知。 只记录模式; 重放不受影响 .
-   健康探测器被记录为一无是处——而不是入境要求,也不是它所支持的。 进入常规探测路径(`/health`, (中文(简体) ), `/healthz`, (中文(简体) ), `/healthcheck`, (中文(简体) ), `/health-check`, (中文(简体) ), `/_health`, (中文(简体) ), `/api/health`, (中文(简体) ), `/api/healthz`, (中文(简体) ), `/readyz`, (中文(简体) ), `/livez`, (中文(简体) ), `/ping`(无) `x-meticulous-session-id` 从不进入抓取语境。 请求其会话名称是真实的 app 流量, 并且无论路径如何被记录, 所以一个 app 仍然可以免费服务 `/api/health` 作为页面数据源。 只记录模式; 重放不受影响 .
-   持久对象的分贝没有有约束力的名称,因为分贝来自 `namespace.get()` 而不是约束自己.
-   第一份文书提出请求之前具有约束力的参考文件`const f = env.SVC.fetch.bind(env.SVC)` 在模块范围)逃避了仪器化. 保持约束 _对象_ 和电话 `.fetch()` 每一请求——SDKs通常做的事情——都被捕获.
-   WebSocket升级和TCP套接字(`connect()`)没有被俘.
-   `fetch` 在请求之外打电话的人 `withMeticulous` (如: `scheduled` 处理者)没有被俘.
-   postgres.js 查询记录,但 **没有在工人内部重放d**:在"Worker"中制作的一款录音在"Node"上重播的应用程序运行时由"Node"的模拟商店提供回放. 一个工人重放 到达真正的数据库.

## 常见问题

### @alwaysmeticulous/backend-recorder-workerd 是什么？

Cloudflare Workers\(工人\)的默契后端记录器 shim\. HTTP在开发记录期间向当地的Meticulous记录器侧车报告进出的捕获事件\.

### 如何安装 @alwaysmeticulous/backend-recorder-workerd？

在项目目录运行 npm install @alwaysmeticulous/backend-recorder-workerd，或使用 pnpm add / yarn add / bun add。

### @alwaysmeticulous/backend-recorder-workerd 支持 TypeScript 吗？

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

### @alwaysmeticulous/backend-recorder-workerd 支持 ESM 还是 CommonJS？

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

### @alwaysmeticulous/backend-recorder-workerd 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20\.19\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @alwaysmeticulous/backend-recorder-workerd 可以商用吗？

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

### @alwaysmeticulous/backend-recorder-workerd 的下载量有多少？

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

### @alwaysmeticulous/backend-recorder-workerd 还在维护吗？

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