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

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

版本：1\.10\.0
npm 元数据更新时间：2026-11-11T02:40:22.771Z
中文译文更新时间：2026-11-11T09:51:44.058Z
软件包许可：MIT

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

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

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

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

## 中文简介

确定Cloudflare Turnstile Siteverify 符号验证.

## 安装

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

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

## README

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

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

WIP Cloudflare Turnstile 服务器侧 Siteverify 仿真器. 它从来没有解决或提出真正的挑战.

## 安装

```sh
bun add @crvouga/mockingbird-service-turnstile
```

## 使用量

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

// Test setup: a local Siteverify, and a token like the one the widget hands the browser.
const server = await createServer()
const { token } = await server.runtime.instance().issue({
  hostname: "app.example.test", action: "signup",
}).json()

// Application code: the Siteverify call it makes to Cloudflare, sent to the emulator's URL.
const siteverifyUrl = `${server.url}/turnstile/v0/siteverify`
const result = await fetch(siteverifyUrl, {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ secret: "mock_secret", response: token }),
})
console.log(await result.json()) // success, challenge_ts, hostname, action, cdata

await server.close()
```

运行 `mockingbird-turnstile serve --port 12126`,然后覆盖消费者的 Siteverify URL 与 `http://localhost:12126/turnstile/v0/siteverify`。保留真正的 Cloudflare 来源于 生产。 不存在通用消费环境变量. 发送合成 `secret: mock_secret`; 配置额外的站点 `sites`。 。 。 .

### 合同

`POST /turnstile/v0/siteverify` 接受 JSON 或 URL 编码的窗体字段 `secret`, (中文(简体) ), `response`, (中文(简体) ), 选项 `remoteip` 和 UUID 编辑器 `idempotency_key`返回 HTTP 200 和 `success: true` 有元数据。 拒绝为 HTTP 200 与 `success: false` 财务报告和审定财务报表 `error-codes`而不是一个运输例外。 失踪/无效的秘密、失踪/无效的标志、, 畸形体和已过期/已使用的代号保留所记录的错误代码.

Tokens在模拟器时钟上以5分钟过期并被消耗一次. 匹配一能性 密钥重试重放原响应; 其他重试返回 `timeout-or-duplicate`。 。 。 . 错误的秘密不会消耗有效的符号 。 应用程序必须独立检查返回 主机名/ 动作 。 远程IP被接受,不用于实际的机器人检测.

### 控件

-   `POST /__admin/issue`: 发出合成符; 接受 `siteKey` (默认) `mock_site`, (中文(简体) ), `hostname`, (中文(简体) ), `action`, (中文(简体) ), `cdata`。默认仅用于本地测试.
-   构造器 `tokens` 共享 `/__admin/state/tokens`:种子标志过期/使用状态.
-   `GET /__admin/attempts`:只进行元数据核查,没有秘密/托接机构.
-   共享时钟,时间线,重置,状态,断层和请求日记都有. 重置还原 构造站点/托盘; 命名空间被信头隔离或 `/__admin/ns/{namespace}`。 。 。 . 身体秘密不选择命名空间 . `adminPrefix` 移动控制树.

预设 : `internal_error` (HTTP 200核查拒绝), `rate_limited` (标注为429), `server_error` (503个), `connection_drop`通用过失规则增加了确定性延迟. 运输预设是测试控制,而不是声称正常Siteverify状态代码. 没有网友.

测试使用原始获取( 请求的客户端), JSON/ 格式成功, 过期边界/ 重放, 单能、输入错误、命名空间/重置隔离、编辑的日记和服务于HTTP 超时/关闭失败行为 。 物业测试验证 判断和检测差异. `bun scripts/parity.ts` 需求 `TURNSTILE_TEST_SECRET` 设定为云花一 所记录的 公用假键; 生产密钥被拒绝 。 比较JSON中的成功/错误信封 并形成模式,而不是生产令牌或私人元数据.

### 故意不模拟

浏览器部件/标本, 机器人检测, 真正的挑战/托盘, 多段编码, 生产 签名、IP声誉、主机名政策管理和企业元数据. 地方决定性地保留缺额和冲突/飞行中的关键政策 代理;只有相同的重试行为才包括在公共合同证据中.

## API 密码

-   `TurnstileAPI`: 用 `fetch`, (中文(简体) ), `reset`, (中文(简体) ), `issue`,以及地点/托盘/试收.
-   `createRuntime`:共享仿真器合同外加象征性的签发/试探.
-   `TURNSTILE_NAMESPACE`:服务名.
-   `TURNSTILE_PRESETS`: 命名失败控制.
-   `document`, (中文(简体) ), `operationIds`, (中文(简体) ), `supportedOperationIds`: 生成了 OpenAPI 元数据.
-   `createServer`, (中文(简体) ), `serveTarget`, (中文(简体) ), `DEFAULT_PORT` 从 `./server`:节点HTTP/CLI服务, 默认端口 12126.

公共类型包括: `Site`, (中文(简体) ), `Token`, (中文(简体) ), `TurnstileAPIOptions`, (中文(简体) ), `OperationId` 财务报告和审定财务报表 `SupportedOperationId`。 。 。 .

## 常见问题

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

确定Cloudflare Turnstile Siteverify 符号验证\.

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

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

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

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

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

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

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

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

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

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

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

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