安装 fastknife/ajcaptcha 后需重点解决请求头、像素缓存和框架缓存适配三处问题：确认 gd/openssl 扩展启用、php≥7.1；laravel 中须配置兼容 cache::store() 的缓存构造器并开启 is_cache_pixel；前端改用 application/x-www-form-urlencoded 请求头并排除 csrf 验证；校验必须调用 captchaservice::check() 并处理返回数组，及时 delete token 防重放。
直接用 composer require fastknife/ajcaptcha 安装，再配好缓存和 GD 扩展，就能跑起来——但多数人卡在请求头、像素缓存和框架缓存适配这三处。
确认 PHP 环境和扩展是否就绪
AJ-Captcha 依赖 gd 和 openssl，缺一不可。Laravel 项目启动时不会主动报这两项缺失，但调用 block_puzzle 或 click_word 时会静默失败或返回空白图。
- 运行
php -m | grep -E "gd|openssl"确认已启用 - 若用 Docker，检查
Dockerfile是否包含docker-php-ext-install gd openssl - PHP 版本必须 ≥ 7.1（当前稳定版
fastknife/ajcaptchav2.1.0 已支持 PHP 8.3）
Laravel 中配置缓存驱动与 pixel 缓存开关
默认的 Fastknife\Utils\CacheUtils 是基于文件的简易缓存，不兼容 Laravel 的 Cache::store() 接口，会导致验证码校验始终失败——因为生成时存的是文件缓存，而校验时 Laravel 去 Redis 查了空 key。
- 必须重写
cache.constructor配置，例如 Laravel 10+ 推荐写成：'constructor' => [Illuminate\Support\Facades\Cache::class, 'store'] - 开启像素缓存能显著提升滑动图生成速度：
'block_puzzle' => ['is_cache_pixel' => true]，但换背景图后要手动清缓存，否则旧像素数据仍被复用 - 若发现滑动图加载慢，先关干扰图：
'is_interfere' => false，比调大memory_limit更有效
前端请求头和 CSRF 兼容问题
Laravel 默认开启 CSRF 保护，而 AJ-Captcha 前端 SDK（如 anji-plus/captcha）默认发 application/json 请求，会被 Laravel 拦截并返回 419 错误。
- 必须把前端请求头改成
application/x-www-form-urlencoded，否则VerifyCsrfToken中间件直接拒掉 - 后端路由需排除 CSRF 验证，例如在
app/Http/Middleware/VerifyCsrfToken.php的$except数组里加：'captcha/*' - 若用 Laravel Sanctum 或 API 路由，注意
api中间件组默认不含web的 session，验证码无法绑定用户态，得切回web路由组
验证逻辑不能只靠前端传来的 token
前端 JS 提交的 token + pointJson 只是输入，Laravel 控制器里必须显式调用 CaptchaService::check()，且要捕获返回的布尔值和错误信息——很多人只判 if ($result)，却忽略 $result 实际是 array{success: bool, msg: string} 结构。
- 正确写法示例：
use Fastknife\Captcha\Service\CaptchaService;<br><br>$result = CaptchaService::check($request->token, $request->pointJson);<br>if (!$result['success']) {<br> return response()->json(['msg' => $result['msg']], 400);<br>} -
pointJson是前端轨迹数据字符串，不是 JSON 对象，别用json_decode()多解一层 - 校验通过后，建议立刻调用
CaptchaService::delete($request->token)清除缓存，防重放
最易被忽略的是缓存驱动的实例获取方式——Laravel 不同版本对 Cache::store() 的返回类型处理不同，有的返回 Repository，有的返回 Store，而 AJ-Captcha 内部只认 PSR-16 接口。硬塞一个不兼容的实例，会导致 set() 成功但 get() 返回 null，整个流程看似正常，实则校验永远失败。
