# @hcaptcha/loader 中文文档

规范地址：https://npmcn.com/package/%40hcaptcha/loader/

版本：2\.4\.2
npm 元数据更新时间：2026-07-16T18:57:38.055Z
中文译文更新时间：2026-11-17T17:50:47.719Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40hcaptcha/loader
原文对照：https://npmcn.com/package/%40hcaptcha/loader/?lang=original
项目主页：https://github.com/hCaptcha/hcaptcha-loader#readme
源码仓库：https://github.com/hCaptcha/hcaptcha-loader

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

- 包体积（解压后）：197 kB，20 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2023-10-11T22:20:31.508Z
- 最新版本发布：2026-07-16T18:57:37.567Z
- 近 30 天下载量：4696691（2026-10-18 至 2026-11-16，npm 官方下载统计）
- 已发布版本数：28（近 12 个月 4 个）

## 中文简介

这是一个 JavaScript 库, 以方便配置 hCaptcha JS 客户端 SDK 的内置错误处理.

## 安装

```sh
npm install @hcaptcha/loader
```

也可以使用：`pnpm add @hcaptcha/loader`、`yarn add @hcaptcha/loader`、`bun add @hcaptcha/loader`

## README

# h Captcha 装入器

这是 JavaScript 库, 便于配置装入 [h 卡普察语Name](https://www.hcaptcha.com/) JS客户SDK有内置错误处理. 它还包括一个重试机制,在hCaptcha脚本由于网络或出乎意料的问题而未能加载时会尝试多次加载.

> [h 卡普察语Name](https://www.hcaptcha.com/) 是一个用于 reCAPTCHA 的保护用户隐私的倒置.
> 
> 报名到 [h 卡普察语Name](https://www.hcaptcha.com/) 去拿你的地钥匙. **要使用此库需要一个站点键 .**

-   [h Captcha 装入器](https://npmcn.com/package/%40hcaptcha/loader/#readme-hcaptcha-loader)
    -   [安装](https://npmcn.com/package/%40hcaptcha/loader/#readme-installation)
    -   [执行情况](https://npmcn.com/package/%40hcaptcha/loader/#readme-implementation)
    -   [道具](https://npmcn.com/package/%40hcaptcha/loader/#readme-props)
    -   [遗产支助](https://npmcn.com/package/%40hcaptcha/loader/#readme-legacy-support)
        -   [导入套装](https://npmcn.com/package/%40hcaptcha/loader/#readme-import-bundles)
        -   [类型脚本](https://npmcn.com/package/%40hcaptcha/loader/#readme-typescript)
        -   [光盘N](https://npmcn.com/package/%40hcaptcha/loader/#readme-cdn)
    -   [社区支助方案](https://npmcn.com/package/%40hcaptcha/loader/#readme-csp)
    -   [哨兵](https://npmcn.com/package/%40hcaptcha/loader/#readme-sentry)

## 安装

```
npm install @hcaptcha/loader
```

或者使用UNPKG通过CDN加载, [说明如下:](https://npmcn.com/package/%40hcaptcha/loader/#readme-CDN)。 。 。 .

## 执行情况

```js
import { hCaptchaLoader } from '@hcaptcha/loader';

await hCaptchaLoader();

hcaptcha.render({
  sitekey: '<your_sitekey>'
});

const { response } = await hcaptcha.execute({ async: true });
```

## 道具

| 名称 | 数值/类型 | 需求 | 默认 | 说明 |
| --- | --- | --- | --- | --- |
| `loadAsync` | 布尔 | 没有 | `true` | 设定是否同步装入脚本 . |
| `cleanup` | 布尔 | 没有 | `false` | 设置后删除脚本标记 . |
| `crossOrigin` | 字符串 | 没有 | `anonymous` | 设定"匿名"等脚本交叉出自属性. |
| `scriptSource` | 字符串 | 没有 | `https://js.hcaptcha.com/1/api.js` | 设置脚本源 URI. 胜过 `secureApi`。 。 。 . |
| `scriptLocation` | HTML 元素 | 没有 | `document.head` | 附加脚本标签的位置 。 确保将其添加到一个将持续防止在同一文档视图中多次加载的区域. |
| `secureApi` | 布尔 | 没有 | `false` | 见企业文件. |
| `apihost` | 字符串 | 没有 | `-` | 见企业文件. |
| `assethost` | 字符串 | 没有 | `-` | 见企业文件. |
| `endpoint` | 字符串 | 没有 | `-` | 见企业文件. |
| `hl` | 字符串 | 没有 | `-` | 见企业文件. |
| `host` | 字符串 | 没有 | `-` | 见企业文件. |
| `imghost` | 字符串 | 没有 | `-` | 见企业文件. |
| `recaptchacompat` | 字符串 | 没有 | `-` | 见企业文件. |
| `reportapi` | 字符串 | 没有 | `-` | 见企业文件. |
| `sentry` | 布尔 | 没有 | `-` | 见企业文件. |
| `uj` | 布尔 | 没有 | `-` | 见企业文件. |
| `custom` | 布尔 | 没有 | `-` | 见企业文件. |

## 遗产支助

为了支持更古老的浏览器,会生成一个单独的捆绑,其中将所有ES6代码编译为ES5并附带一个可选的多填装捆绑.

-   `polyfills.js`: 为旧浏览器中不支持的特性提供多填充.
-   `index.es5.js`数字 : **@hcaptcha/ loader (英语)** 为ES5环境编译了软件包.

### 导入套装

生成的两个捆绑都使用IIFE格式而不是更现代的导入语法,例如 `require` 或者说 `esm`。 。 。 .

```js
// Optional polyfill import
import '@hCaptcha/loader/dist/polyfills.js';
// ES5 version of hCaptcha Loader
import '@hCaptcha/loader/dist/index.es5.js';

hCaptchaLoader().then(function(hcaptcha) {
    var element = document.createElement('div');
    // hCaptcha API is ready
    hcaptcha.render(element, {
        sitekey: 'YOUR_SITE_KEY',
        // Additional options here
    });
});

```

### 类型脚本

要用ES5版本处理打字符,请使用以下语句.

```ts
declare global {
  interface Window {
    hCaptchaLoader: any;
  }
}
```

### 光盘N

针对更老浏览器的 hCaptcha 装入器也可以通过 CDN 导入 [联科办](https://www.unpkg.com/),见下文实例.

```html
<!DOCTYPE html>
<head>
    <script type="text/javascript" src="https://unpkg.com/@hcaptcha/loader@latest/dist/polyfills.js"></script>
    <script type="text/javascript" src="https://unpkg.com/@hcaptcha/loader@latest/dist/index.es5.js"></script>
</head>
<body>
<div id="container"></div>
<script type="text/javascript">
    hCaptchaLoader().then(function(hcaptcha) {
        // hCaptcha API is ready
        hcaptcha.render('container', {
            sitekey: 'YOUR_SITE_KEY',
            // Additional options here
        });
    });
</script>
</body>
</html>
```

## 社区支助方案

请注意,你应该使用 `strict-dynamic` 该加载器的策略,因为它需要装入 SDK 通过 `appendChild()`。 。 。 .

## 哨兵

通过设置 `sentry` 标记为假,这样可以防止客户端错误报告发送到我们.

```js
hCaptchaLoader({ sentry: false });
```

## 常见问题

### @hcaptcha/loader 是什么？

这是一个 JavaScript 库, 以方便配置 hCaptcha JS 客户端 SDK 的内置错误处理\.

### 如何安装 @hcaptcha/loader？

在项目目录运行 npm install @hcaptcha/loader，或使用 pnpm add / yarn add / bun add。

### @hcaptcha/loader 支持 TypeScript 吗？

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

### @hcaptcha/loader 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @hcaptcha/loader 可以商用吗？

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

### @hcaptcha/loader 的下载量有多少？

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

### @hcaptcha/loader 还在维护吗？

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

