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

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

版本：3\.11\.0
npm 元数据更新时间：2026-11-11T02:33:51.129Z
中文译文更新时间：2026-11-11T05:53:01.852Z
软件包许可：MIT

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

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

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

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

## 中文简介

PostHog:/flags v2 和 legs/decide 的评价,每测试旗,变体和有效载荷控制,远程配置,gzip/base64捕获(/batch/,/e/,/i/v0/e/),录制收录,特征-flag管理和HogQL API片.

## 安装

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

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

## README

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

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

状态模拟器 **邮箱** 测试套间:远程特征旗评价(`/flags` 页:1 遗产 `/decide` 形状),远程配置,事件抓取(`/batch/`, (中文(简体) ), `/e/`, (中文(简体) ), `/i/v0/e/`, (中文(简体) ), 分会话记录录入、hog-js后资产和调查终点以及片段 管理 API 我们的工具和餐具呼叫(feature-flag list/create/patch, HogQL). 每个旗帜 通过管理路径设定每个测试,因此无法到达我们的应用程序内覆盖路径(限制) 布尔斯人, `getConfig` 有效载荷、EMR服务器闸门、成员-应用程序变体)成为可控制装置,以及 堆栈运行从未达到 `us.i.posthog.com`。 。 。 .

-   行动范围: [支助](https://github.com/crvouga/mockingbird/blob/main/packages/service/posthog/SUPPORT.md)
-   合同`openapi.yaml`)由后浩格-节点5.52.2的线形手写出, `@posthog/core` 1.54.0 (后反应-内生 4.72.1''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 我们自己的原始取来。 所有三个SDK都被证明是与之相反的(`posthog.sdk.test.ts`) (中文(简体) ).

## 安装

```bash
npm install -D @crvouga/mockingbird-service-posthog
```

仅限无害环境管理。 节点 22或 Bun 1.2. 无土生属地. 给它服务 `npx mockingbird-posthog serve`, (中文(简体) ), `createServer` 从 `./server` (节点),或 `createRuntime` 与 任何获取服务器.

## 使用量

将应用的 PostHog 主机指向模拟器( 默认为8795 端口 ) :

| 应用 | 变量 |
| --- | --- |
| 后端(旗子、抓取、网站购买槽) | `POSTHOG_HOST`, (中文(简体) ), `POSTHOG_API_KEY` |
| EMR 后端 | `POSTHOG_HOST`, (中文(简体) ), `POSTHOG_API_KEY` |
| EMR 前端( 浏览器后hog- js 和服务器原始抓取) | `NEXT_PUBLIC_POSTHOG_HOST`, (中文(简体) ), `NEXT_PUBLIC_POSTHOG_KEY` |
| 成员应用 | `public-config.json[stage]` 主机,或 `?POSTHOG_HOST=&POSTHOG_API_KEY=` 在线(G-P1) |
| Python 补充管理服务 | `POSTHOG_HOST` |

```bash
npx mockingbird-posthog serve --port 8795 --import-flags dev
```

```ts
import { PostHog } from "posthog-node"
import { createRuntime } from "@crvouga/mockingbird-service-posthog"

// Test setup: the emulator and the flags this worker should see.
const emulator = createRuntime()
const admin = (path: string, body: unknown, method = "PUT") =>
  emulator.fetch(
    new Request(`http://posthog.test/__admin${path}`, { method, body: JSON.stringify(body) }),
  )
// Per-worker namespaces: map each worker's project token (the SDKs cannot add headers)…
await admin("/credentials", { credentials: { phc_worker1: "w1" } })
// …then set flags in that namespace.
await admin("/flags/shop-coupons?namespace=w1", { default: true })
await admin("/flags/rx-category-intake?namespace=w1", {
  default: true,
  payload: { categories: ["trt"] },
  overrides: [{ distinct_id: "42", value: false }, { email: "qa@example.test", value: "beta" }],
})
await admin("/flags/mobile-smart-links?namespace=w1", undefined, "DELETE") // absent again

// The application's posthog-node client. Only its fetch changes: requests reach the
// emulator in this process instead of us.i.posthog.com.
const posthog = new PostHog("phc_worker1", {
  fetch: (url, options) => emulator.fetch(new Request(url, options)),
})
await posthog.getFeatureFlag("shop-coupons", "7") // true
await posthog.getFeatureFlag("rx-category-intake", "42") // false
posthog.capture({ distinctId: "7", event: "coupon_applied" })
await posthog.shutdown()
```

### 路线

| 路线 | 行为 |
| --- | --- |
| `POST /flags/?v=2` (单位:千美元)`&config=true`(中文(简体) ) | 后浩格-节点,后浩克-反应-内生,后浩克-js. 体质 `{token, distinct_id, person_properties?, groups?, flag_keys_to_evaluate?, …}`答复 `{flags: {<key>: {key, enabled, variant, reason, metadata: {id, version, description, payload?}}}, errorsWhileComputingFlags, requestId, evaluatedAt}`· ; `payload` 这是JSON **字符串** 并且只伴有启用的旗帜. `config=true` 添加远程配置字段 . |
| `POST /flags?v=2` | 同样的路线,没有后遗症: EMR前端的生取,身体 `{api_key, distinct_id, person_properties?}`。 。 。 . |
| `POST /flags/` (无) `v`,或 `v=1`, (中文(简体) ), `POST /decide/?v=3` | 遗产形状 `{featureFlags: {k: bool | variant}, featureFlagPayloads: {k: "<json>"}, errorsWhileComputingFlags, config, …}` (Python客户端). `/decide/?v=4` 回答 v2 形状 . |
| `GET /array/{token}/config`, (中文(简体) ), `…/config.js` | 远程配置 : `{supportedCompression: ["gzip","gzip-js"], hasFeatureFlags: true, analytics: {endpoint: "/i/v0/e/"}, sessionRecording: false | {endpoint: "/s/"}, surveys: false, …}`; 数据 `.js` 窗体组合 `window._POSTHOG_REMOTE_CONFIG[token]`。 。 。 . `hasFeatureFlags` 总是真实的(假使后hog-react-native跳过旗下加载). |
| `POST /batch/` | `{api_key, batch: [{event, distinct_id, properties, timestamp, uuid}], sent_at}`,通常情况下 `Content-Encoding: gzip`。 。 。 . |
| `POST /e/`, (中文(简体) ), `POST /i/v0/e/` | 一个事件,一系列事件,或者 `{api_key, batch}`; 身体可能是生的gzip (`gzip-js`),基数64 `data=` 表单( 表格)`compression=base64`),或叫"JSON". 已知事件 `uuid` 被贬低. |
| `POST /s/` | 会议记录: 已计(`GET /__admin/recordings`),从未被存储. |
| `GET /static/recorder.js`, (中文(简体) ), `/static/{ver}/recorder.js` | 惰性脚本. |
| `GET /api/surveys/?token=`, (中文(简体) ), `/api/web_experiments/?token=` | `{surveys: []}`, (中文(简体) ), `{experiments: []}`。 。 。 . |
| `GET/POST /api/projects/{id}/feature_flags/`, (中文(简体) ), `GET/PATCH …/{flagId}/` | 需要持枪者私人钥匙。 列表页面 `{count, next, previous, results}` (单位:千美元)`limit`编号 :`offset`• 旗帜 `filters.groups` 编号 : `multivariate` 编号 : `payloads` 从旗子模型中衍生出来;实验旗保留了完整的变种配置,并创建/patch parse `filters` (见下文). `flagId` 是数字代号还是密钥. |
| `GET/POST /api/projects/{id}/experiments/`, (中文(简体) ), `GET/PATCH …/{experimentId}/` | 项目实验的个人钥匙管理:名称,参数,度量衡,日期,存档状态,以及活相接的旗帜. 新的旗帜草稿有控制/测试变体,不活动;设置 `start_date` 激活它们 设置 `end_date` 或者说 `archived` 保留了旗帜活动。 列表是最新的第一位,带有终止限制/抵消链接(包括命名空间前缀). 遗留变体/滚出/负载参数草案更新了共享旗;正在运行的旗帜更改使用特征旗 API. |
| `POST /api/projects/{id}/query/` | 猪肉QL `{query: {kind: "HogQLQuery", query}}` → `{results, columns}` 从罐装的答案(`PUT /__admin/settings {"queryResults": […]}`, (中文(简体) ), `{results: []}` 否则. |

每条路线都用它后面的斜线来回答。 错误使用 PostHog `{type, code, detail, attr}` 机构: 401 `invalid_api_key` 没有项目代号,400 `missing_distinct_id`、400个 `invalid_payload` 404 为不可毁谤的身体 `not_found`。 。 。 .

### 旗帜语义

-   **缺席对 `false`。 。 。 .** 一个旗子,它的 `default` 省略(或 `null`) 完全没有返回 除非一个覆盖匹配; `default: false` 返回时 `enabled: false`成员应用软件 `hasFlag` 仅因缺席而发生静态默认。 非活动或删除 旗帜从不返回(如PostHog).
-   **目标:** 按顺序排列 `distinct_id` 或通过 `person_properties.email` 默认值.
-   **备选案文:** 字符串值是一个变体(`enabled: true, variant: "<key>"`我们的后端, EMR和Python客户端都读作 `true`。 。 。 .
-   **有效载荷 :** 任意 JSON; 存储并发送为 JSON 字符串 PostHog 使用. 后门的 `getConfig` 只接受物体有效载荷.
-   **管理层 `filters` • 型号:** `distinct_id` 编号 : `email` 财产组合成为被取代; 100%的无财产群体为默认(其 `variant`,否则最大多变量 变体,其他 `true`);在0%或部分推出时是 `false`; 组和其他财产 团体被忽略(决定性,不散开). 创建/ patch 拒绝数组/ scalar `filters.payloads` 在改变旗帜或链接之前使用 400 实验状态。 字典要求对照 [PostHog 的序列器回归](https://github.com/PostHog/posthog/blob/282f536aa98f6de6f03d92ec719ba2e25cab0239/products/feature_flags/backend/api/test/test_filters_schema.py#L219) 和当地合同;种子 `172181039` 通过自我均等,而不是现场管理平等.

### 管理员(超过标准合同)

| 路线 | 效果 |
| --- | --- |
| `PUT /__admin/flags/:key` | `{default?: bool | "variant" | null, payload?: any, overrides?: [{distinct_id? | email?, value?, payload?}], active?, name?}`. 弃权 `default` 使得每个人的旗子都不存在 上面的名字。 弹出 `metadata.version`。 。 。 . |
| `DELETE /__admin/flags/:key` | 删除旗帜( 缺席 ) . |
| `PUT /__admin/flags` | 块数 : `{flags: {<key>: spec}, replace?: true}` 或者说 `[{key, …spec}]`。 。 。 . |
| `GET /__admin/flags`, (中文(简体) ), `GET /__admin/flags/:key` | 名字空间的旗帜. |
| `GET /__admin/flags/evaluate?distinct_id=&email=` | 什麽 `/flags` 对这一主题的答复,如 `{flags: {key: value}}`。 。 。 . |
| `POST /__admin/flags/import` | `{from: "state.json", env: "dev" | "prod", project?: "member-app" | "emr", replace?}` 消费者应用软件的捆绑副本中的种子 `docs/feature-flags/state.json` (或通过) `state: {flags: […]}` 。 。 . `live` → `true` (或最大变体), `rollout 0` 编号 : `targeted` 编号 : `ramping` → `false`, (中文(简体) ), `inactive` 编号 : `missing` ——缺席. |
| `POST /__admin/flags/bump` | 不更改服务器侧; 返回 a `generation` 计数器。 文件记录的清除应用程序旗下缓存的时刻(后端) `getAllFlagsAndPayloads` 每个用户60 s;EMR前端服务器60 s / 10 s. |
| `GET /__admin/events?distinct_id=&event=&since=` | 被俘事件,最古老的`since`: 时代 ms 或 ISO, 模拟时钟. `$exception` 仅保留 `$lib`, (中文(简体) ), `$lib_version`, (中文(简体) ), `$exception_level`, (中文(简体) ), `$session_id`;每个事件(以及来自 `$set`) (中文(简体) ). |
| `GET /__admin/recordings` | `{count}` 联 合 国 `/s/` 员额. |
| `GET/PUT /__admin/settings` | `{sessionRecording?: bool, queryResults?: [{match?, columns?, results}]}`。 。 。 . |

错误预设( E)`POST /__admin/faults {"preset": "<name>", "count"?: n}`· ; `GET /__admin/faults/presets`, (中文(简体) ), 每个人在 `/flags` 财务报告和审定财务报表 `/decide`数字 : `flags_5xx`, (中文(简体) ), `flags_429` (单位:千美元)`retry-after: 1`, (中文(简体) ), `flags_hang` (1.5 s,通过后端严格和EMR 1 s s 比赛), `errors_while_computing` (单位:千美元)`errorsWhileComputingFlags: true`旗帜还在, `quota_limited` (单位:千美元)`quotaLimited: ["feature_flags"]`没有旗帜。 加号 `capture_5xx` 在捕捉的终点. 每个预设每个路线都增加一条规则,所以 `count` 每个路线适用.

### 命名空间

PostHog SDK 无法添加信头 。 选择命名空间 :

-   **主机前缀** (小学): `POSTHOG_HOST=http://127.0.0.1:8795/__admin/ns/w1`。每个 SDK 构建 `${host}/path`这样 `/__admin/ns/w1/flags/?v=2` 选择 `w1`。 。 。 .
-   **项目令牌**数字 : `PUT /__admin/credentials {"credentials": {"phc_…": "w1"}}`。符号是 读取自 `/array/{token}/…`, (中文(简体) ), `?token=`,尸体(`token`, (中文(简体) ), `api_key`,或者第一个批次的 事件 `properties.token`,在解码gzip/base64后,或个人钥匙的 `Authorization: Bearer` 在管理API.
-   `x-mockingbird-namespace`对原始客户来说.

管理API的 `next` 页面 URL 保存已配置的管理员前缀和名空间. 在每个页面请求中发送授权头中的个人密钥 .

### 故意不模拟

-   推出、组别、组(组织)目标确定和地方评价的百分比 (单位:千美元)`/api/feature_flag/local_evaluation`:旗帜从明确角度进行确定性评估 覆盖和默认.
-   实验统计、接触群、计量执行、特别发射/存档/船舶终点、批准政策、高级试验过滤器以及 `feature_flag` 配置通过实验写出. 管理旗使用现有的全名空间项目别名模型;实验记录额外通过项目id过滤.
-   会话记录内容,热映射,调查和网络实验(端点回答为空).
-   HogQL执行:查询回答罐头结果.
-   人物简介 : `$identify` 编号 : `$set` 事件为断言而存储,但不反馈 目标; 发送 `person_properties` 打开 `/flags` 就像SDK一样.
-   按管理API上的工程id进行项目隔离:每个命名空间设置一面旗.
-   真正的远程配置字段 超过SDKs读取.

## API 密码

| 导出 | 仁爱 | 说明 |
| --- | --- | --- |
| `PostHogAPI` | 类 | 进程模拟器 : `fetch(request)`, (中文(简体) ), `reset()`, (中文(简体) ), `evaluate(subject, keys?)`, (中文(简体) ), `events(query?)`, (中文(简体) ), `flagList()`, (中文(简体) ), `state`选项: `sqlite`, (中文(简体) ), `now`, (中文(简体) ), `namespace`, (中文(简体) ), `flags`, (中文(简体) ), `settings`。 。 。 . |
| `createRuntime` | 函数 | 全面服务合同的仿真器(保健、管理员、前缀/托肯/标题的命名空间、预设、日记)。 选项 : `flags`, (中文(简体) ), `settings`, (中文(简体) ), `clock`, (中文(简体) ), `seed`, (中文(简体) ), `adminKey`, (中文(简体) ), `onLog`, (中文(简体) ), `sqlite`。 。 。 . |
| `POSTHOG_PRESETS` | 对象 | 每个命名的断层预设. |
| `POSTHOG_NAMESPACE` | 字符串 | 服务名称, `"posthog"`。 。 。 . |
| `evaluateFlag` | 函数 | 评价一个旗帜记录 `{distinct_id, person_properties}` (单位:千美元)`undefined` = 缺席). |
| `parseFlagSpec` | 函数 | 将管理旗帜机构验证为 `FlagSpec`。 。 。 . |
| `payloadString` | 函数 | 邮电站存储时的有效载荷(JSON字符串,或 `null`) (中文(简体) ). |
| `specsFromState`, (中文(简体) ), `valueForState` | 函数 | 地图a `state.json` 文件(或一个旗帜国)改为旗帜规格. |
| `ACME_FLAG_STATE` | 对象 | 消费者应用软件的捆绑和修剪本 `docs/feature-flags/state.json`。 。 。 . |
| `decodePostHogBody`, (中文(简体) ), `tokenFromBody` | 函数 | 取消 PostHog 机身信封(gzip, gzip-js, base64) `data=`); 在一个体内找到项目标志. |
| `scrubProperties` | 函数 | 在存储前应用了事件财产洗涤. |
| `document`, (中文(简体) ), `operationIds`, (中文(简体) ), `supportedOperationIds` | 数值 | 销售商为OpenAPI合同及其业务代号. |
| `createServer`, (中文(简体) ), `serveTarget`, (中文(简体) ), `DEFAULT_PORT` (单位:千美元)`./server`(中文(简体) ) | 节点 | 服务过来 `node:http`; 数据 `serve` CLI目标(`--import-flags dev|prod`, (中文(简体) ), `--session-recording`; 蚌埠8795. |

部分 [嘲笑鸟](https://github.com/crvouga/mockingbird)。 。 。 .

## 常见问题

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

PostHog:/flags v2 和 legs/decide 的评价,每测试旗,变体和有效载荷控制,远程配置,gzip/base64捕获\(/batch/,/e/,/i/v0/e/\),录制收录,特征-flag管理和HogQL API片\.

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

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

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

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

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

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

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

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

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

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

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

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