XCaptcha-for-Typecho 新一代的Typecho验证插件

更新日志

[1.3.1] - 2025-11-23

Fixed

  • 修复Altcha PHP72的兼容性问题，PHP72没有JSON_THROW_ON_ERROR(PHP73引入)，会导致./lib/class.altcha.php报错
  • 修复登陆界面验证码占位符不消失以及按钮无法启用的bug(issue #8)
  • 修复评论区验证码占位符不消失的bug
  • 优化Altcha样式

[1.3.0] - 2025-10-10

Fixed

  • 修复了Altcha未正确返回值导致评论异常问题
  • 修复了PHP8.2不支持动态创建属性而报错(./lib/class.geetestlib.php文件)，前端请求Action接口获取到的是报错信息而非JSON文本，最终导致JSON解析出错Geetest验证码渲染失败的问题。

[v1.3.0 pre-release]

Added

  • 添加了渲染组件以及校验成功的回调函数，用于禁用/启用按钮和提示验证码组件正在加载

[v1.2.1]

Fixed

  • 移除./includes/XCaptcha_Config.php的personalConfig方法
  • 修复Typecho控制台 -> 个人配置 显示XCaptcha配置找不到的bug(issue #1 )

[v1.2.0]

Added

  • 添加了altcha，纯本地的工程量计算的验证码方案

[v1.1.1]

Deprecated

  • 极验证加载不再依赖JQuery，启用JQuery与JQuery CDN URL项已被移除

Changed

  • 对代码进行重构，做了结构性优化

Added

  • 添加管理员评论无需验证功能，此项为可选项
  • 兼容Typecho 1.1旧版本

[v1.0.2]

Changed

  • 修改部分可能引发歧义的字段名称

Added

  • 支持修改验证接口地址
  • 添加"极验证展现方式"设置项
  • 验证码尺寸样式选项支持极验证

[v1.0.1]

Fixed

  • 修复了极验证jQuery CDN失效的Bug
  • 原默认使用字节跳动的CDN加载jQuery，部分地区可能加载失效，现在默认采用jsDelivr

Added

  • 支持在配置页面启用或禁用插件自带的jQuery，对于部分自带jQuery的主题（如Handsome）无需启用该项
  • 为了避免资源失效，支持在配置页修改jQuery CDN地址，此项仅在勾选启用插件自带的jQuery选项后生效

Others

  • 本插件的jQuery仅用于极验证，对其它验证码的使用无影响。

起因

之前由于博客垃圾评论过多，因此想要找一个验证码插件来给评论提交添加验证。一开始我用的是本地的数字图片验证码，后来在别人项目的基础上改进了CairBin/typecho-plugin-geetest。

但是这个仅支持极验证，如果需要用Google reCaptcha等还需要重新上传，于是便打算自己写一个支持多种验证码的插件。

Github项目地址 CairBin/XCaptcha

支持验证码类型

目前支持的验证码如下：

考虑接下来支持：

  • Google reCaptcha v3
  • 极验证Geetest v4

使用方式

下载本项目

可以通过Git获取本项目：

git clone https://github.com/CairBin/XCaptcha.git

或者下载本项目的压缩包

wget https://github.com/CairBin/XCaptcha/archive/refs/heads/main.zip

以上两种方式通常包含插件最近提交的代码，包括正在开发的功能和补丁，但也有可能不稳定，建议去Release页面下载Release版本。

解压后需要将插件文件夹的名称改为XCaptcha。

配置插件

将XCaptcha文件夹上传到你的Typecho博客的usr/plugins/目录下，在Typecho后台的插件面板里激活即可。

从上述所支持验证码的官网注册账户，然后获取你站点的Captcha ID和Secret Key，有的也叫Site Key和Secret Key，本质上都一样，对应公钥和私钥。前者用于前端标识可以公开，后者用于服务端向验证码服务器校验需要保密。

修改主题模板的comments.php文件，主题目录是usr/themes/your_theme/，在评论提交按钮之前或者表单最后添加一行代码，然后回到博客后台配置插件，将获取到的ID/Key填写进去，以及配置其他参数即可。

<?php if (array_key_exists('XCaptcha', Typecho_Plugin::export()['activated'])) : XCaptcha_Plugin::showCaptcha(); endif; ?>

如果你想要禁用评论提交按钮，经过验证后才可点击提交表单，只需要给按钮添加类custom-submit-button即可，以默认主题为例：

<button type="submit" class="custom-submit-button submit"><?php _e('提交评论'); ?></button>

Altcha配置

Altcha采用本地验证方案，自动生成HMAC密钥，无需手动填写Captcha ID和Secret Key

部分主题可能不存在comments.php文件，这时候你需要从其他文件里找到评论表单，并在合适的位置添加这行代码。

插件导致无法登陆后台

登陆页面启用验证码，如果配置不当，会导致验证一直失败而无法进入博客后台。

如果遇到这种问题，请修改Typecho的数据库的typecho_options表中，name属性为plugins的那一行的值为a:0:{}以禁用所有插件。

非常重要：在进行此操作前请务必备份数据库！

URL参数填写说明

  • “验证码JS地址”取决于网络情况，它会替代原本引入的验证初始化脚本（不是二次验证的接口），遇到某些JS加载缓慢时使用，如果不明白留空即可。“校验地址”用于更换服务端验证接口，留空使用默认地址，一般在默认接口无法访问或者失效时填写。
  • 区分JQuery CDN URL与上述部分，JQuery CDN URL用于通过CDN引入JQuery（不能留空），默认使用jsdelivr，而上述部分是用于初始化/校验验证码。
  • 如果勾选了开启登陆页面验证码则，注册页面也会跟着开启，前提是你启动了注册功能。

PJAX回调问题

据反馈部分主题开启PJAX无刷新后可能会导致验证码加载不正常，请根据主题自行设置PJAX回调函数。Handsome主题经过测试可以正常使用，其他主题若存在此问题请在issue反馈，但是部分作者没使用过的付费主题可能难以适配。

PHP8兼容性问题

于v1.3.0正式版兼容PHP8，并在PHP82环境下通过测试。详细请参看“重要版本说明”部分和CHANGELOG.md。

PHP72兼容性问题

于v1.3.1版本优化了Altcha PHP72的兼容性，PHP72没有JSON_THROW_ON_ERROR(PHP73引入)，会导致./lib/class.altcha.php报错

重要版本说明

关于v1.1.0及后续版本

  • XCaptcha v1.1.0及后续版本，极验证加载不再依赖JQuery，启用JQuery与JQuery CDN URL项已经被移除。
  • 自此版本起兼容旧版本的Typecho 1.1

关于v1.2.1版本及后续版本

通过移除./includes/XCaptcha_Config.php的personalConfig方法，修复Typecho控制台 -> 个人配置 显示XCaptcha配置找不到的bug(issue #1 )

关于v1.3.0及后续版本

  • v1.3.0版本添加了渲染组件成功以及校验成功的回调函数，用于禁用/启用按钮以及提示验证码组件正在加载，因此对于hcaptcha、cloudflare以及recaptcha在配置cdnUrl的时候需要设置onload参数为beforeCheckCallback，例如https://hcaptcha.com/1/api.js?onload=beforeCheckCallback（更具体的参数配置并不属于本文范畴，你应当参考所使用验证码的官方文档）
  • v1.3.0本分为预发布测试版和正式版，预发布版本存在altcha评论错误以及PHP8下极验证无法渲染问题，在v1.3.0正式版已经修复，Release页面的预发布版本已经删除，现在可下载的都是正式版本，建议及时更新。

关于v1.3.1及其后续版本

  • 自v1.3.1版本，优化了Altcha PHP72的兼容性

反馈

反馈bug请提交issue仓库，请务必声明Typecho版本号、XCaptcha版本号、使用主题、Apache版本/Nginx版本等信息，方便问题复现。此外最好备注站点信息，方便作者查看问题。

项目展示

登录界面

插件配置

评论区

特别感谢

本项目在编写时参考的插件项目：

最后修改：2025 年 11 月 25 日
© 允许规范转载
如果觉得我的文章对你有用，请随意赞赏