如何实战配置ThinkPHP验证码参数？

本文共计928个文字，预计阅读时间需要4分钟。

如果您在ThinkPHP项目中安装了验证码扩展但出现异常、格式不正确或功能失效，很可能是因为验证码参数未正确配置或配置结构不匹配。以下是对不同版本和环境的验证码参数配置方法：

一、手动创建并配置config/captcha.php文件

ThinkPHP 6 默认不自带captcha.php配置文件，必须手动创建该文件，否则会抛出“Class 'think\captcha\Captcha' not found”或初始化失败错误；该文件需返回一个关联数组，且至少包含length和useZh等基础键，结构与TP5不兼容。

1、在项目根目录下的config/子目录中新建captcha.php文件（若无config目录则先创建）。

2、写入以下基础配置内容（确保使用UTF-8无BOM编码）：

立即学习“PHP免费学习笔记（深入）”；

3、保存后确认文件路径为config/captcha.php，且PHP可读取该文件。

4、验证是否生效：在控制器中调用Captcha::create()或访问验证码路由，观察输出是否符合配置预期。

二、配置字体路径与背景色参数

font_path必须为绝对路径，相对路径在CLI模式下将无法定位字体文件；bg参数必须为RGB数值数组，十六进制字符串（如'#ff0000'）会导致静默失败、页面空白或回退默认灰底。

1、下载支持中文的TrueType字体（如simhei.ttf），放入public/fonts/目录。

2、在captcha.php中设置'font_path' => __DIR__ . '/../public/fonts/simhei.ttf'。

3、设置背景色为'bg' => [245, 245, 245]，而非'bg' => '#f5f5f5'。

4、确保web服务器对public/fonts/目录具有读取权限。

三、启用中文验证码的三要素配置

中文验证码显示需同时满足三个条件：开启useZh开关、提供zhset字符集、加载UTF-8兼容中文字体；缺一不可，否则会出现方块、乱码或纯英文输出。

1、在captcha.php中设置'useZh' => true。

2、指定中文字符集，例如'zhset' => '你|我|他|好|学|习|思|维|验|证'。

3、确认font_path指向的字体文件真实存在且能正常渲染中文（推荐simhei.ttf或msyh.ttc）。

4、检查当前PHP环境的默认字符集是否为UTF-8，可在phpinfo()中查看default_charset项。

四、适配HTTPS与反向代理环境

验证码图片URL默认以http://开头，在HTTPS站点中触发Mixed Content拦截；前后端分离或Nginx反向代理时，session域名不一致也会导致校验始终失败。

1、在captcha.php中显式配置'url' => '/captcha/refresh'，避免协议前缀自动生成。

2、检查config/session.php中的'domain'配置，设为空字符串''或统一主域'.example.com'。

3、若使用captcha_src()辅助函数，需确认app.url_domain配置未强制注入http://前缀。

4、在Nginx配置中确保proxy_cookie_domain与实际访问域名一致，例如proxy_cookie_domain ~^(?:www\.)?(.+)$ $1;。

五、规避高干扰参数组合引发的识别率暴跌

fontSize超过30、length大于6、disturb设为true三者叠加，会因GD库渲染时字体重叠、干扰线覆盖关键字符，导致Captcha::check()校验失败率显著上升，而非前端显示问题。

1、将'fontSize'控制在18–26之间，优先保障字符清晰可辨。

2、将'length'设为4或5，避免用户输入疲劳及OCR误判率升高。

3、若需增强安全性，优先启用'useNoise' => true而非'disturb' => true，前者干扰更可控。

4、禁用'useCurve'或仅在'fontSize' ≤ 22且'length' ≤ 4时启用。