# @friendlycaptcha/server-sdk 中文文档

规范地址：https://npmcn.com/package/%40friendlycaptcha/server-sdk/

版本：0\.3\.0
npm 元数据更新时间：2026-03-16T14:22:41.072Z
中文译文更新时间：2026-11-15T14:12:02.737Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40friendlycaptcha/server-sdk
原文对照：https://npmcn.com/package/%40friendlycaptcha/server-sdk/?lang=original
项目主页：https://github.com/FriendlyCaptcha/friendly-captcha-javascript#readme
源码仓库：https://github.com/FriendlyCaptcha/friendly-captcha-javascript

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

- 包体积（解压后）：111 kB，38 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2024-01-08T13:27:34.461Z
- 最新版本发布：2026-03-16T14:22:40.807Z
- 近 30 天下载量：10810（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：6（近 12 个月 3 个）

## 中文简介

方便 Captcha V2 API 的服务器端客户端 SDK

## 安装

```sh
npm install @friendlycaptcha/server-sdk
```

也可以使用：`pnpm add @friendlycaptcha/server-sdk`、`yarn add @friendlycaptcha/server-sdk`、`bun add @friendlycaptcha/server-sdk`

## README

# 友好的captcha-javascript

[![NPM Version badge](https://img.shields.io/npm/v/%40friendlycaptcha/server-sdk)](https://www.npmjs.com/package/@friendlycaptcha/server-sdk)

一个 Javascript 客户端 [友好的卡普查语Name](https://friendlycaptcha.com/) 服务。 这个客户端可以方便地与友好的Captcha API整合和验证Captcha响应.

> 这个图书馆是用来 [友谊 Captcha v2](https://developer.friendlycaptcha.com/) 只有这个 如果你在找V1,请看 [这里](https://docs.friendlycaptcha.com/)

**这是您在后端代码中使用的库**。关于您在前端使用的代码,请参见 [@ 友好的captcha/ sdk](https://github.com/FriendlyCaptcha/friendly-captcha-sdk)。 。 。 .

## 安装

**使用 [国家预防机制](https://npmjs.com/)**

```shell
npm install @friendlycaptcha/server-sdk
```

## 使用量

下面是一些如何使用客户的基本例子.

以更详细的例子来看 [实例](https://npmcn.com/package/%40friendlycaptcha/server-sdk/example) 目录.

### 初始化

```javascript
import { FriendlyCaptchaClient } from "@friendlycaptcha/server-sdk";

const frcClient = new FriendlyCaptchaClient({
  apiKey: "YOUR_API_KEY",
  sitekey: "YOUR_SITEKEY",
});
```

### 正在验证 Captcha 响应

打电话后 `verifyCaptchaResponse` 使用 captcha 响应后,结果对象上有两个功能,您应当检查:

-   `wasAbleToVerify()` 说明我们是否能够核实Captcha的答复。 这将是 `false` 以防网络/我们的服务出现问题或配置出现错误.
-   `shouldAccept()` 说明Captcha的答复是否正确。 如果客户端以非限制性模式运行( 默认) 和 `wasAbleToVerify()` 已返回 `false`,这将是 `true`。 。 。 .

下面是这种行为的一些例子.

#### 校验准确的随机反应

```javascript
const result = await frcClient.verifyCaptchaResponse("CORRECT_CAPTCHA_RESPONSE_HERE");
console.log(result.wasAbleToVerify()); // true
console.log(result.shouldAccept()); // true
```

#### 验证一个不正确的控制反应, 且不会出现问题 :

```javascript
const result = await frcClient.verifyCaptchaResponse("INCORRECT_CAPTCHA_RESPONSE_HERE");
console.log(result.wasAbleToVerify()); // true
console.log(result.shouldAccept()); // false
```

#### 在非限制性模式下运行( 默认) 时验证对问题( 网络问题或不良配置) 的错误的 captcha 响应 :

```javascript
const result = await frcClient.verifyCaptchaResponse("INCORRECT_CAPTCHA_RESPONSE_HERE");
console.log(result.wasAbleToVerify()); // false
console.log(result.shouldAccept()); // true
```

#### 严格运行时验证对问题(网络/服务问题或不良配置)的错误回应:

```javascript
const frcClient = new FriendlyCaptchaClient({
  ...
  strict: true,
});

const result = await frcClient.verifyCaptchaResponse("INCORRECT_CAPTCHA_RESPONSE_HERE");
console.log(result.wasAbleToVerify()); // false
console.log(result.shouldAccept()); // false
```

### 获取风险情报

您可以为给定的符号获取风险情报数据 。 这提供了关于请求风险状况的详细资料,包括网络数据、地理定位、浏览器细节和风险分数.

```javascript
const result = await frcClient.retrieveRiskIntelligence("RISK_INTELLIGENCE_TOKEN_HERE");

// Check if we were able to retrieve the risk intelligence data
if (result.wasAbleToRetrieve()) {
  // Check if the token is valid and data was retrieved successfully
  if (result.isValid()) {
    const response = result.getResponse();
    console.log("Risk Intelligence Data:", response.data);
  } else {
    // Token was invalid or expired
    const error = result.getResponseError();
    console.log("Error:", error?.error_code, error?.detail);
  }
} else {
  // Network issue or configuration problem
  if (result.isClientError()) {
    console.log("Configuration error - check your API key");
  } else {
    console.log("Network issue or service temporarily unavailable");
  }
}
```

### 配置

### 配置

客户端提供多个配置选项:

-   **键**: 您的友好 Captcha API 密钥 .
-   **站台密钥**您的友好卡普查网站密钥.
-   **严格**: (可选) 如果客户端完全无法验证 Captcha 响应( 例如网络故障或配置错误) , 默认 `verifyCaptchaResponse` 返回时 `true` 随便 路过 `strict: true`它会回来 `false` 相反:每个答复都需要严格核实.
-   **尾点**: (可选)站点校验API的端点域. 简称 `eu` 或者说 `global` 还接受。 默认是 `global`。 。 。 .
-   **获取**: (可选) 获取要使用的执行 。 默认为 `globalThis.fetch`。 。 。 .

## 发展

### 安装依赖关系

```shell
npm install
```

### 运行测试

首先运行 SDK 测试服务器,然后运行 `npm test`。 。 。 .

```shell
docker run -p 1090:1090 friendlycaptcha/sdk-testserver:latest

npm test
```

### 生产建筑

```shell
npm run build:dist
```

## 许可证

开源 [麻省理工学院](https://npmcn.com/package/%40friendlycaptcha/server-sdk/LICENSE)。 。 。 .

## 常见问题

### @friendlycaptcha/server-sdk 是什么？

方便 Captcha V2 API 的服务器端客户端 SDK

### 如何安装 @friendlycaptcha/server-sdk？

在项目目录运行 npm install @friendlycaptcha/server-sdk，或使用 pnpm add / yarn add / bun add。

### @friendlycaptcha/server-sdk 支持 TypeScript 吗？

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

### @friendlycaptcha/server-sdk 支持 ESM 还是 CommonJS？

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

### @friendlycaptcha/server-sdk 可以商用吗？

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

### @friendlycaptcha/server-sdk 的下载量有多少？

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

### @friendlycaptcha/server-sdk 还在维护吗？

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