ThinkPHP6验证码在国内环境跑通的关键在于配置正确而非安装，需手动创建UTF-8无BOM的config/captcha.php，配置url、session、HTTPS及中文字体等参数，并启用Session中间件。
ThinkPHP6验证码在国内环境跑通，关键不在“装没装”，而在“配得对不对、验得稳不稳”。国内常见问题：验证码不显示、验证总失败、HTTPS下报错、中文乱码、Nginx反代后失效——这些问题90%都出在配置环节，而非代码逻辑。
一、必须手动创建 config/captcha.php
TP6默认不带该文件，缺了就直接报错 Class 'think\captcha\Captcha' not found。不能跳过这步：
- 在项目根目录的 config/ 文件夹下新建 captcha.php
- 文件编码必须是 UTF-8无BOM，否则中文配置失效
- 返回标准关联数组，至少包含 length 和 useZh（即使不用中文也要显式设为 false）
- 示例基础配置（适配国内主流环境）：
'length' => 4,
'codeSet' => '23456789abcdefghjkmnpqrstuvwxyzABCDEFGHJKLMNPQRTUVWXY',
'useCurve' => true,
'useNoise' => true,
'fontSize' => 28,
'imageW' => 180,
'imageH' => 60,
'bg' => [248, 248, 248], // 必须是 RGB 数组，不能写 #f8f8f8
'expire' => 1800,
'useZh' => false,
];
二、HTTPS与Nginx反向代理必配项
国内站点基本全站HTTPS，但验证码默认生成 http:// 开头的图片 URL，浏览器会拦截 Mixed Content；Nginx 反代时 session.domain 不一致也会导致校验失败。
- 在 captcha.php 中强制指定 url 参数，用相对路径：
- 'url' => '/captcha/refresh',
- 确保 Nginx 配置中已透传 Host 和 X-Forwarded-Proto 头（尤其宝塔/阿里云SLB环境）
- 检查 PHP 的 session.cookie_secure 是否为 true（HTTPS 下需开启），同时确认 session.domain 为空或与当前域名完全匹配（如 .yourdomain.com）
三、中文验证码三要素齐全才生效
想显示“登录|验证|安全”这类中文？光开 useZh 不行，必须同时满足：
立即学习“PHP免费学习笔记（深入）”；
- useZh => true
- zhset 字符串用竖线分隔，例如：'zhset' => '登|录|安|全|验|证|保|护'
- font_path 指向真实存在的中文字体文件，且路径为绝对路径：
- 'font_path' => __DIR__ . '/../public/fonts/simhei.ttf',
- public/fonts/simhei.ttf 文件需存在，Linux 下注意权限（chmod 644），Windows 下推荐用 simsun.ttc 或 msyh.ttc
四、验证失败？先查 Session 是否启用
TP6 默认不自动初始化 Session，验证码校验依赖 session 存储原始码，没 Session 就永远验不过。
- 打开 app/middleware.php，取消注释这一行：
- \think\middleware\SessionInit::class,
- 或者在登录控制器顶部手动启动（适合局部启用）：
- use think\facade\Session;
Session::start(); - 验证时统一用 facade 方式调用：if (!\think\facade\Captcha::check($captcha)) { ... }
