---
title: WordPress
---

# WordPress

CaptchaLa 官方 WordPress 插件。无需编写任何代码，即可为 WordPress 核心表单以及主流表单、电商和社区插件添加 CAPTCHA 验证。

## 覆盖范围

下列每一项在插件设置面板中都是独立的复选框 —— 只勾选您实际想要保护的入口即可。

- WordPress 登录
- WordPress 注册
- WordPress 评论
- WordPress 找回密码
- WooCommerce 结账
- WooCommerce 注册账号
- WooCommerce 登录
- Contact Form 7
- Gravity Forms
- WPForms
- Elementor Forms
- BBPress（主题与回复）
- BuddyPress（注册与动态）

如果某个表单插件未安装，对应的开关会自动隐藏 —— 插件在启动时会探测当前可用的集成。

## 安装

### 1. 安装插件

插件已上架官方 WordPress.org 插件目录：
[**wordpress.org/plugins/captchala**](https://wordpress.org/plugins/captchala)。两种方式：

- **WordPress 后台**（推荐）—— 进入 `插件` → `安装插件`，搜索 `CaptchaLa`，点击 **安装** 然后 **启用**。此后即可一键更新。
- **手动上传** —— 从
  [`wordpress.org/plugins/captchala`](https://wordpress.org/plugins/captchala)
  下载 zip 包，在 `插件` → `安装插件` → `上传插件` 处上传并启用。

插件要求 WordPress ≥ 6.0 与 PHP ≥ 7.4。

### 2. 获取密钥

在 [`dash.captcha.la`](https://dash.captcha.la) 注册账号，创建一个应用，然后复制：

- **App Key** —— 公钥，会嵌入到页面中
- **App Secret** —— 仅在服务端使用，由 WordPress 用于调用 `/v1/validate`

### 3. 配置接入

在 WP 后台左侧菜单打开 `CaptchaLa`：

1. 粘贴 **App Key** 与 **App Secret**。
2. 选择一种验证模式（popup、bind、embed 或 float —— 参见 [Web SDK](/zh-CN/web-sdk)）。
3. 勾选需要保护的表单。
4. 点击 **保存更改**。

打开任意一个已保护的表单（建议使用隐私窗口）以确认挑战正常渲染。

## 配置项

所有设置都位于 `WP 后台 → CaptchaLa`。插件将它们以单个 WordPress option（`captchala_settings`）保存。

| 配置项 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| App Key | string | — | 来自 CaptchaLa 控制台的公钥（`cl_pub_…`）。必填。 |
| App Secret | string | — | 服务端密钥。必填。不会暴露给浏览器。 |
| 验证模式 | enum | `popup` | 可选 `popup`、`bind`、`embed`、`float`。对应 Web SDK 的 `product` 选项。 |
| 表单开关 | bool[] | 全部关闭 | 每个支持的表单一个开关（参见 [覆盖范围](#覆盖范围)）。 |
| 懒加载 | bool | `true` | 开启后，仅在包含受保护表单的页面才会加载 CaptchaLa loader。 |
| 主题 | enum | `auto` | `light`、`dark`，或 `auto`（跟随用户系统设置）。 |
| Action 标签 | string | 按表单 | 验证时上送的 `action` 字符串（`login`、`register`、`comment`、`wc_checkout` 等）。插件已设置合理默认值，仅在有特定需求时覆盖。 |
| 绑定 IP | bool | `true` | 在签发与验证时附带访客 IP。若部署在不转发客户端 IP 的反向代理后请关闭。 |
| 验证失败时阻断 | bool | `true` | 关闭后，验证失败仅记录日志，表单仍会提交。适合灰度上线，不建议生产环境使用。 |

设置也可以从设置页底部以 JSON 形式导出 / 导入。

## 常见问题

**插件免费吗？**

是的，WordPress 插件本身免费。CaptchaLa 免费额度为每月 10,000 次验证 —— 仅在需要更高用量时才会涉及付费计划。

**会拖慢我的站点吗？**

loader 是懒加载的，只在渲染了受保护表单的页面才会引入。多数地区下验证调用由边缘节点在 100ms 以内返回。首页不会注入任何跟踪脚本。

**支持 WooCommerce 吗？**

支持。结账、注册和登录开箱即用，每项都是独立的开关。插件挂接 WooCommerce 标准的校验管线，因此验证失败会以普通的 WooCommerce 表单错误展示。

**需要写代码吗？**

不需要。安装、粘贴两个密钥、勾选要保护的表单即可。如有自定义需求，也提供了若干 filter 钩子，但都是可选的。

**符合 GDPR 吗？**

CaptchaLa 以隐私优先：不加载任何第三方跟踪像素、不上送广告信号，WordPress 插件只传输完成单次挑战所必需的数据。可通过 CaptchaLa 控制台按请求导出或删除数据。

## 源码

- WordPress.org 插件目录：[`wordpress.org/plugins/captchala`](https://wordpress.org/plugins/captchala)
- 插件仓库：[`github.com/Captcha-La/captchala-wordpress`](https://github.com/Captcha-La/captchala-wordpress)
- 问题反馈 / 需求建议：在上述仓库提 issue
- 相关文档：[Web SDK](/zh-CN/web-sdk) · [PHP 服务端 SDK](/zh-CN/sdk/server-php) · [API 参考](/zh-CN/api-reference)