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

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

版本：3\.11\.0
npm 元数据更新时间：2026-11-11T02:11:42.057Z
中文译文更新时间：2026-11-11T02:31:28.227Z
软件包许可：MIT

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

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

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

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

## 中文简介

状态仿真 开源Formbricks:客户端环境状态(种子有合成调查程序),响应创建 上游验证和{代码,消息,细节}错误,v1管理 API,部件脚本,并签名 respo

## 安装

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

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

## README

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

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

开源状态仿真器 **[窗体砖](https://github.com/formbricks/formbricks)** (6.x) 用于 测试套件:客户端环境说明 JS SDK 的加载调查,响应创建 上游验证和 `{code, message, details}` 错误, v1 管理 API( 答复和 调查, `x-api-key`),部件脚本 网络 SDK 负载,以及响应管道 **`responseCreated` 编号 : `responseFinished` 网络用户**每个命名空间都有一个小的种子 合成调查体`src/corpus/surveys.json`:核动力源、登入、产品反馈、链接 调查和暂停调查;发明内容).

-   行动范围: [支助](https://github.com/crvouga/mockingbird/blob/main/packages/service/formbricks/SUPPORT.md)
-   合同`openapi.yaml`)由上游Formbricks 6.0.0的路由处理器手写 编辑 [文档](https://formbricks.com/docs)。 。 。 .

## 安装

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

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

## 使用量

指着SDK `appUrl` 在模拟器上(和您的管理 API 基础 URL),使用工作空间 id `cworkspace000000000000001` (或其遗留环境d) `cenvironment0000000000001`,随着年长 SDKs发送),以及任何管理API密钥.

```bash
npx mockingbird-formbricks serve --port 8813 \
  --webhook-url http://127.0.0.1:3000/webhooks/formbricks \
  --webhook-secret "whsec_…"
```

用你自己的设置和调查来启动它,没有包装程序或一个 `PUT` 启动后 :

```bash
npx mockingbird-formbricks serve \
  --settings '{"workspaces": ["cworkspace000000000000002"], "legacyEnvironmentIds": {"cenvironment0000000000002": "cworkspace000000000000002"}}' \
  --surveys ./surveys.json
```

`--settings <json|file>` (或 `MOCKINGBIRD_SETTINGS`,或舰队进入 `settings`) 采取 领域 `GET|PUT /__admin/settings`,用其类型检查(拼错的密钥是错误)。 他们 是每个命名空间的默认值, 重设返回, 以及您给的替换字段 内置值整数( give) `legacyEnvironmentIds` 而默认的环境别名已消失. `--workspace-id` 添加到脚上 `workspaces`。 。 。 . `--surveys <file>` (一清单,或 `{surveys: [...]}`(中文(简体) ) 在每个命名空间 都加上了你的调查 并且它们都活下来了 调查 (或更早的一行)已经跳过的人的身份证 `workspaceId` 服务于 每个配置的工作空间,以及 `type`, (中文(简体) ), `status` 和遗产 `environmentId` 处理方式为 `PUT /__admin/surveys` 处理他们. `--surveys-mode replace` 将文件作为整体. 在舰队,设定 `options: {"surveys": "surveys.json"}`。 。 。 .

```ts
import { WORKSPACE_ID } from "@crvouga/mockingbird-service-formbricks"
import { createServer } from "@crvouga/mockingbird-service-formbricks/server"

// Test setup: the emulator, posting response webhooks to the app's handler.
const server = await createServer({
  webhooks: { url: "http://127.0.0.1:3000/webhooks/formbricks", secret: "whsec_…" },
})

// Application code: appUrl is server.url. Submit a response to the seeded NPS survey.
const appUrl = server.url
const created = await fetch(`${appUrl}/api/v2/client/${WORKSPACE_ID}/responses`, {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({
    surveyId: "csurveynps000000000000001",
    finished: true,
    data: { nps_score: 9 },
  }),
})
// → {data: {id, quotaFull: false}}. The emulator validates it, stores it, and posts
// responseFinished to the webhook.

// Test control: read what was stored.
const stored = await fetch(`${appUrl}/__admin/responses`)
await server.close()
```

### 路线

客户端路由在路径中选择工作空间 id 或 遗留( 前为 Formbricks-5) 环境 id ; 两者均 决心在同一工作空间.

| 路线 | 行为 |
| --- | --- |
| `GET /api/v1/client/{workspace}/environment` | `{data: {data: {surveys, actionClasses, workspace, project}, expiresAt}}` (单位:千美元)`project` 是上游遗留下来的别名 `workspace`) (中文(简体) ). 仅 `app` 调查 `inProgress`在SDK的勘测地上 `projectOverwrites` 镜像 `workspaceOverwrites`错误的ID是400 `Invalid ID format`; 一个未知的 404 `Workspace not found`。 。 。 . |
| `POST /api/v2/client/{workspace}/responses` | `{surveyId, finished, data, contactId?, meta?, …}` → `{data: {id, quotaFull: false}}`。未知的工作空间为 404;输入错误为 400 `Fields are missing or incorrectly formatted` 带 zod 4 `details` (单位:千美元)`{surveyId: "Invalid cuid2", finished: "Invalid input: expected boolean, received undefined"}`· ; `userId` 不属于 v2 输入的一部分,被忽略; a `contactId` 关闭联系人时为 403 (企业); 未知调查 404; 对另一个工作空间的调查 400 `Survey is part of another workspace`; 调查没有 `inProgress` 403 (韩语) `Survey is not accepting submissions`。 。 。 . `data` 仅保留元素 id 和 已声明的隐藏字段 (`hiddenFields.fieldIds`);其他密钥被丢弃. 在元素验证之前, a `multipleChoiceSingle` 或者说 `multipleChoiceMulti` 值(字符串,或数组中的任何字符串),在响应语言中等于无选择标签——正文 `language`,或标签的 `default` 当它被省略时; `getLocalizedValue` 不退后——超过250个字符是400 `Response exceeds character limit` 与 `details: {questionId}`,没有储存。 准确的标签匹配不检查长度;没有匹配的250个字符或更少字符的条目通过此检查. 元素校验默认为存在于 `data` (成否. `validation: "finished-validates-all"` (前# 7292 Formbricks) 检查每个元素当 `finished` 真实的,只有现在的,当它是虚假的;失败的,是400,而储存什么。 任何一种方式:要求 `Please fill out this field`; 选择要素选项以外的选择( 当它没有“ 其他” ) − `Please enter a valid format`; 打开电子邮件/ url/ 电话 % `Please enter a valid …`; 400 (英语) `Validation failed` 与 `details: {"response.data.<elementId>": "<messages joined by '; '>"}`。 。 。 . `meta` 保留 `source`, (中文(简体) ), `url`, (中文(简体) ), `action` 和自动抓取的页面 / UTM / 屏幕密钥,加 `userAgent` 财务报告和审定财务报表 `country` (从) `CF-IPCountry`) (中文(简体) ). `language` 划线化(`en` → `en-US`); 已完成的回复 `ttc` 收益 `_total`。 。 。 . |
| `GET /api/v1/management/responses?surveyId=&limit=&skip=` | `{data: [response]}`,最先更新;未知 `surveyId` 404号. |
| `GET /api/v1/management/responses/{id}` | `{data: response}` 或者404号. |
| `GET /api/v1/management/surveys?limit=&offset=` | `{data: [survey]}`,最近更新的第一. |
| `POST /api/v1/management/surveys` | `{workspaceId (or legacy environmentId), name, type?, status?, blocks | questions}` → `{data: survey}`. 遗产 `questions` 成为每个块一个; 二者或两者都不是 400; 缺少的工作空间 id 是 400 `workspaceId must be provided`,一个未知的404. |
| `GET /api/v1/management/surveys/{id}` | `{data: survey}` 或者404号. |
| `GET /js/formbricks.umd.cjs` | 无操作脚本定义 `window.formbricks` (每个SDK方法解决). |

管理调查 `questions` 来源于 `blocks` (块上最后一个按钮标签) 要素), `workspaceId`遗产 `environmentId`,以及 `projectOverwrites`管理路线 需求 `x-api-key` (任何非空密钥,除非 `apiKeys` ),否则401 `{code: "not_authenticated", message: "Not authenticated", details: {"x-Api-Key": "…"}}`。 。 。 .

### 网络呼号

`POST <webhook-url>` 与 `{webhookId, event, data: {...response, survey: {title, type, status, createdAt, updatedAt}}}`,标题 `webhook-id`, (中文(简体) ), `webhook-timestamp` 当终点有 `whsec_…` 暗号, `webhook-signature: v1,<base64 HMAC-SHA256>` (标准网呼). 只有事件 a 端点订阅发送 : `responseFinished` 默认(`events: ["responseCreated", "responseFinished"]` 两者均适用). `--webhook-token` 附录a `?token=` 对检查一个的接收器. 报复, `GET /__admin/webhooks`, (中文(简体) ), `…/events`, (中文(简体) ), `…/replay`, (中文(简体) ), `…/flush` 财务报告和审定财务报表 `PUT /__admin/webhook-endpoints` 工作如常.

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

| 路线 | 效果 |
| --- | --- |
| `GET /__admin/responses?surveyId=` | 存储的反应,最古老的第一. |
| `GET|PUT /__admin/surveys` | 阅读或添加/替换调查(`[{id, name, type?, status?, workspaceId?, blocks?, questions?, …}]`; 无 `workspaceId` = 由每个配置的工作空间服务). |
| `GET|PUT /__admin/contacts` | 读取或添加联系人`[{id, userId?, attributes?, workspaceId?}]`用于 `contactId` 回应. |
| `GET|PUT /__admin/settings` | `{workspaces?, legacyEnvironmentIds?, apiKeys?, webhookId?, contactsEnabled?, validation?}`。 。 。 . `validation` 实值 `present-only` (默认,7292后为Formbricks)或 `finished-validates-all` (在#7292前:一个完成的回复验证了每个元素). `createRuntime({settings})` 接受相同的字段. |

错误预设( E)`POST /__admin/faults {"preset": "<name>", "count"?: n}`· ; `GET /__admin/faults/presets`: `rate_limited` (429个) `too_many_requests`, (中文(简体) ), `server_error` (500个), `missing_response_id` (储存,但 答案中没有编号, `environment_unavailable`, (中文(简体) ), `data_as_string` (管理层) `data` 作为JSON 字符串, `management_unauthorized`, (中文(简体) ), `connection_drop`, (中文(简体) ), `duplicate` (下个网钩两次), `webhook_drop`, (中文(简体) ), `webhook_reorder`。 。 。 .

### 命名空间

`x-mockingbird-namespace`页:1 `/__admin/ns/<name>` 应用程序 URL 前缀,或者通过证书:工作空间 (或遗留环境) id 在客户端路径( SDK 无法添加信头) 或管理器中 `x-api-key`,通过 `PUT /__admin/credentials {"credentials": {"<workspace id or key>": "<namespace>"}}`。 。 。 .

### 故意不模拟

-   显示、 联系人/ 识别, `user` 财务报告和审定财务报表 `storage` 客户端 API (部件脚本) 的路由 是无操作的,所以SDK从不给它们打电话; 响应更新( S)`PUT …/responses/{id}`) (中文(简体) ).
-   配额(总是) `quotaFull: false`),单用链接,PIN保护,reCAPTCHA,电子邮件 校验、文件上载检查、自定义 `validation.rules`, (中文(简体) ), 调查逻辑,以及关于创建的全部调查计划(仅检查上面的形状).
-   超过允许列表的嵌入式数据吸收合同(封闭字段、强制、大小限制), `userAgent` 解析( 总是) `{device: "desktop"}`),和超越通俗的语言卡通化 光线密码.
-   组织、 API- key 权限(`unauthorized`,其他管理层 API (原始内容存档于2019-10-21). Formbricks UI.

## API 密码

| 导出 | 仁爱 | 说明 |
| --- | --- | --- |
| `FormbricksAPI` | 类 | 进程模拟器 : `fetch(request)`, (中文(简体) ), `reset()`, (中文(简体) ), `responses()`, (中文(简体) ), `render(record)`, (中文(简体) ), `wireSurvey(survey)`, (中文(简体) ), `pipeline(event, record, survey)`, (中文(简体) ), `state`选项: `sqlite`, (中文(简体) ), `now`, (中文(简体) ), `namespace`, (中文(简体) ), `surveys`, (中文(简体) ), `settings`, (中文(简体) ), `onWebhook`。 。 。 . |
| `createRuntime` | 函数 | 全面服务合同的仿真器(健康、管理、命名空间、证书、预设、网络呼号)。 选项 : `webhooks: {url, secret?, events?, retryDelaysMs?, fetch?}`, (中文(简体) ), `surveys` (取代保护令; `serve --surveys` 阑尾, `settings`, (中文(简体) ), `clock`, (中文(简体) ), `seed`, (中文(简体) ), `adminKey`, (中文(简体) ), `onLog`, (中文(简体) ), `sqlite`。 。 。 . |
| `FORMBRICKS_PRESETS` | 对象 | 每个命名的断层预设. |
| `FORMBRICKS_NAMESPACE` | 字符串 | 服务名称, `"formbricks"`。 。 。 . |
| `WEBHOOK_PATH` | 字符串 | 实例的常规接收路径, `/webhooks/formbricks`。 。 。 . |
| `formbricksCredential` | 函数 | 请求中包含的工作空间 id 或 API 密钥 . |
| `formbricksError` | 函数 | 构建窗体砖' `{code, message, details}` 错误反应 . |
| `validateResponseData` | 函数 | 上游元素验证 : `(survey, data, language?, {validation?, finished?})` → `{elementId: messages}` 或者说 `null`。 。 。 . |
| `CORPUS_SURVEYS` | 价值 | 合成的测量仪器 每一个命名空间都有种子. |
| `WORKSPACE_ID`, (中文(简体) ), `ENVIRONMENT_ID`, (中文(简体) ), `DEFAULT_SETTINGS` | 数值 | 默认的工作空间,其遗留环境 id,以及默认设置. |
| `document`, (中文(简体) ), `operationIds`, (中文(简体) ), `supportedOperationIds` | 数值 | 销售商为OpenAPI合同及其业务代号. |
| `createServer`, (中文(简体) ), `serveTarget`, (中文(简体) ), `DEFAULT_PORT` (单位:千美元)`./server`(中文(简体) ) | 节点 | 服务过来 `node:http`; 数据 `serve` CLI目标; 第8813口. |

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

## 常见问题

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

状态仿真 开源Formbricks:客户端环境状态\(种子有合成调查程序\),响应创建 上游验证和\{代码,消息,细节\}错误,v1管理 API,部件脚本,并签名 respo

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

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

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

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

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

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

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

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

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

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

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

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