hCaptcha人机验证接入CMS

很多站长发现，CMS 开放评论后不久就会涌入大量垃圾评论，手动删除根本忙不过来。给评论表单加一层人机验证是最省事的拦截方式，hCaptcha 免费额度足够个人站点使用，接入也不复杂。下面按零基础也能照做的顺序，讲清楚从获取密钥到验证生效的完整流程。 ## 动手前需要确认的几件事 接入 hCaptcha 不需要改动数据库，但需要你能编辑主题文件。提前确认以下几点，能避免改到一半卡住： - CMS 后台可以正常登录，并且有主题文件编辑权限（宝塔面板路径通常在 `/www/wwwroot/你的站点/wp-content/themes/当前主题/`）。 - 站点已经开启 HTTPS。hCaptcha 要求页面通过 HTTPS 加载，否则验证组件可能不显示。 - 能访问 hCaptcha 官网注册账号。如果服务器在国内且无法直连，需要先确认网络出口是否正常。 - 备份当前主题的 `functions.php` 和评论模板文件，改错时可以快速还原。 ## 注册 hCaptcha 并拿到两把密钥 1. 打开 hCaptcha 官网，用邮箱注册并登录。 2. 进入控制台，点击新建站点（New Site）。 3. 填写站点域名，例如 `example.com`，不要带 `http://` 或路径。 4. 提交后会得到两个值：**Site Key**（前端公钥）和 **Secret Key**（服务端私钥）。 5. 把 Secret Key 保存到只有自己能看的地方，不要写进前端 JavaScript。 Site Key 会出现在页面源码里，属于公开信息；Secret Key 用于服务端向 hCaptcha 发起校验，泄露后别人可以伪造验证结果，所以务必保密。 ## 在评论表单插入验证组件 以常见的 WordPress 类 CMS 为例，评论表单模板一般是主题目录下的 `comments.php`。找到 `

` 标签内提交按钮之前的位置，插入 hCaptcha 的容器和脚本： ```html

``` 如果你的 CMS 使用独立评论插件，优先查看插件是否自带 hCaptcha 选项，有的话直接在插件设置里填入 Site Key 和 Secret Key 即可，不必手动改模板。手动改模板适合没有内置支持的轻量 CMS。 保存后刷新文章页，评论框上方应该能看到一个复选框形式的验证区域。如果看不到，先按 F12 打开浏览器控制台，检查是否有脚本加载失败或 HTTPS 混合内容报错。 ## 服务端校验，决定评论是否放行 只加前端组件不够，攻击者可以绕过页面直接提交评论。必须在服务端把用户提交的 `h-captcha-response` 字段发给 hCaptcha 校验接口。 在主题的 `functions.php` 中，挂载评论提交前的钩子，示例逻辑如下： ```php add_action('pre_comment_on_post', function() { $token = $_POST['h-captcha-response'] ?? ''; if (empty($token)) { wp_die('请先完成人机验证。'); } $resp = wp_remote_post('https://hcaptcha.com/siteverify', [ 'body' => [ 'secret' => '你的Secret Key', 'response' => $token, 'remoteip' => $_SERVER['REMOTE_ADDR'] ?? '' ] ]); $body = json_decode(wp_remote_retrieve_body($resp), true); if (empty($body['success'])) { wp_die('人机验证未通过，请重试。'); } }); ``` 其他 CMS 的思路一致：找到评论提交的处理入口，在写库之前请求 `https://hcaptcha.com/siteverify`，只有 `success` 为 true 才继续保存评论。 ## 容易踩的坑和排查方向 接入过程中最常见的失败不是代码写错，而是细节没对齐： - **域名不匹配**：hCaptcha 控制台填写的域名必须和实际访问域名一致，带 `www` 和不带 `www` 可能被视为两个站点。 - **Secret Key 填错位置**：Secret Key 只能出现在服务端代码里，如果误填到前端，验证会一直失败。 - **缓存干扰**：开启了页面缓存或 CDN 后，旧的评论页可能仍加载不到新脚本，清理缓存再测试。 - **验证通过仍被拦截**：检查服务端请求是否被防火墙拦截，可以在服务器上执行 `curl -I https://hcaptcha.com/siteverify` 看是否能通。 - **主题更新覆盖修改**：直接改主题文件会在更新后丢失，建议用子主题或插件方式保留改动。 ## 怎么确认拦截真的生效了 配置完成后不要只看页面能显示验证框，还要实际走一遍流程： 1. 用无痕窗口打开一篇文章，不勾选验证直接提交评论，应该被拒绝并提示完成验证。 2. 正常勾选验证后提交，评论应能成功发布。 3. 登录 hCaptcha 控制台，查看请求统计是否有对应记录。 4. 观察一到两天，对比开启前后的垃圾评论数量，通常会有明显下降。 如果验证框显示但提交后始终报错，优先检查 Secret Key 是否复制完整、服务器时间是否准确，时间偏差过大也会导致校验失败。 ## 常见疑问 **hCaptcha 免费吗？** 个人站点通常可以使用免费额度，具体限制建议以 hCaptcha 官网当前说明为准。 **会影响正常用户评论体验吗？** 大多数用户只需勾选一次复选框，无感验证场景下甚至不需要手动操作。 **可以同时用多个验证服务吗？** 技术上可以，但没必要，同时加载多套脚本反而拖慢页面。 给 CMS 接入 hCaptcha 的核心就三步：拿到密钥、前端放组件、服务端做校验。任何一步缺失都可能让拦截失效，按本文顺序检查一遍，再观察几天评论数据，基本就能把垃圾评论挡在门外。