captcha_src()报错是TP5.1迁移到TP6.0+的典型兼容断层：v1.x函数式验证码不适用，须升级为topthink/think-captcha:^3.0，改用{:captcha_img('default')}及命名空间think\captcha\Captcha调用。
captcha_src() 报错：函数未定义
这是最典型的兼容断层现象。TP5.1 中的 captcha_src() 是全局辅助函数，由 topthink/think-captcha v1.x 提供；而 TP6.0.1 默认不加载该函数，也不再自动注册 v1.x 的函数别名。
常见错误现象：Call to undefined function captcha_src() 或 captcha_img() 渲染出纯文本而非图片。
- 确认你用的是
topthink/think-captchav1.x（如 v1.0.7），它只适配 TP5.x，**不能直接用于 TP6.0+** - TP6.0+ 官方推荐使用
topthink/think-captchav3.x（对应 ThinkPHP 6.0+ 的驱动重构版） - 执行
composer require topthink/think-captcha:^3.0，不是v1.0.7 - 安装后检查
app/config/captcha.php是否存在；若无，手动复制 vendor/topthink/think-captcha/src/config.php 到该路径并重命名为captcha.php - 模板中改用
{:captcha_img('default')}，注意参数是驱动标识（非必需，但显式传参可避免自动探测失败）
GD 扩展检测失败但实际可用
TP6.0.1 的验证码驱动默认走 think\captcha\driver\Gd，构造时调用 gd_info()；若返回空数组或 ['version' => '']，直接抛异常，导致整个类加载中断——这时你甚至看不到验证码类，只看到“类找不到”或白屏。
这不是扩展没装，而是运行时被拦住了：
立即学习“PHP免费学习笔记（深入）”；
- 检查
php.ini的disable_functions，确认没禁掉imagecreatefromstring、imagecolorallocate、imagepng、gd_info - CLI 和 Web 环境可能用不同
php.ini：在浏览器访问phpinfo()页面，搜索 “GD Support”，确认为 enabled；同时在命令行跑php -r "var_dump(gd_info());"对比输出 - 部分 Docker 镜像（如
php:8.2-apache）需手动启用 GD：docker-php-ext-install gd，并提前装好libfreetype6-dev、libjpeg-dev等编译依赖 - 临时验证：在入口文件
public/index.php顶部加extension_loaded('gd') || die('GD not loaded');，排除加载问题
类名与命名空间变更导致自动加载失败
TP6.0.1 彻底移除了 TP5.x 的函数式调用习惯，所有验证码逻辑封装在命名空间内，且不再自动注入到全局作用域。
如果你在控制器里写了 new \think\captcha\Captcha() 却报“类不存在”，大概率是路径/命名空间写错了：
- TP6.0+ 的正确类名是
think\captcha\Captcha（注意没有反斜杠前缀，且大小写敏感） - 确保已执行
composer dump-autoload，尤其当你手动移动过 vendor 或修改过 autoload 规则 - 不要混用 TP5 的
think\captcha\Captcha（v1.x）和 TP6 的同名类（v3.x）；二者接口不兼容，v3.x 构造器参数、方法签名都变了 - 验证器中校验验证码应改用
'captcha' => 'require|captcha'规则，而非手动调用captcha_check()函数（该函数在 v3.x 中已移除）
文件编码带 BOM 导致输出中断
验证码图片本质是二进制 PNG 流，一旦 PHP 输出缓冲区里混入不可见字符（比如 UTF-8-BOM），HTTP 响应头就会提前发送，后续 imagepng() 就会失败，浏览器收到乱码或空白，开发者误以为“类没找到”。
这个坑非常隐蔽，尤其从非 IDE 编辑器复制代码进来时：
- 检查
app/config/captcha.php、app/controller/Login.php等所有涉及验证码调用的 PHP 文件，是否为 UTF-8 无 BOM 编码 - 用 Notepad++ 打开 → 菜单栏“编码” → 确认显示“UTF-8 无 BOM”；若显示“UTF-8-BOM”，点击转换
- PhpStorm 用户右键文件 → “File Encoding” → 设为 UTF-8，并勾选 “Remove BOM”
- 终端下可用
file -i filename.php查看编码；或head -n1 filename.php | hexdump -C查是否有ef bb bf
升级中最容易被忽略的不是语法改写，而是环境配置和编码细节——GD 检测失败、BOM 干扰、函数名被 disable_functions 拦截，这三者叠加，会让“类找不到”变成一个指向性极差的假象。
