README

Laravel 滑动验证码扩展包。支持 Laravel 8+、PHP 8.0+。

功能特性

自动定时任务：每日零点刷新背景图、每小时清理临时缓存
手动命令：刷新背景图、清理临时图
完整 API：生成、验证、图片鉴权、手动刷新/清理
已验证 Token：验证成功后返回 verified_token，登录时携带校验
IP 频率限制：验证接口、图片接口单 IP 限流
IP 校验：验证时校验与生成时 IP 一致
可配置：尺寸、存储路径、API 参数等

安装

composer require gong86627/laravel-slider-captcha

配置

首次执行任意 php artisan 命令时，若 config/slider-captcha.php 不存在，将自动发布到项目 config/ 目录。

也可手动发布：

php artisan vendor:publish --tag=slider-captcha-config

在 .env 中配置 Pixabay API Key（用于拉取背景图）：

SLIDER_CAPTCHA_API_KEY=your-pixabay-api-key

获取免费 Key：https://pixabay.com/api/docs/

配置说明

config/slider-captcha.php：

配置项	说明	默认值
width	验证码宽度	320
height	验证码高度	155
slider_w	拼图块宽度	65
slider_h	拼图块高度	65
block_l	拼图主体边长	42
block_r	拼图圆弧半径	10
distance_err	位置误差(px)	3
min_slide_time	最小滑动时长(ms)	600
max_slide_time	最大滑动时长(ms)	10000
ip_limit	单IP每分钟验证次数（verify）	5
image_ip_limit	单IP每分钟图片请求次数	20
cache_expire	验证码有效期(秒)	300
verified_token_expire	verified_token 有效期(秒)	60
verified_token_prefix	verified_token 缓存前缀	sliderverified
verify_ip_check	登录校验 verified_token 时是否校验 IP	true
verify_ip_match	验证时是否校验 IP 与生成时一致	true
tolerance	验证容错像素	8
x_margin	X 最小值偏移（图宽-滑块宽-x_margin）	100
save_path	背景图存储路径	slider_captcha/bg_images
temp_path	临时图存储路径	slider_captcha/temp
api_url	背景图 API 地址	https://pixabay.com/api/
api_key	API Key	从 .env 读取
daily_count	每日下载背景图数量	50
per_request	单次 API 请求数量	10
request_delay	请求间隔(秒)	2
max_retry	失败重试次数	3
keywords	背景图搜索关键词	见配置文件
colors	Pixabay 颜色过滤	green,blue,brown,orange
route_prefix	路由前缀	slider-captcha
route_middleware	路由中间件	[]

前端流程

调用 GET /slider-captcha/generate 获取 token、背景图、拼图
用户完成滑动 → 调用 POST /slider-captcha/verify（传 token、puzzle_x、slide_time、track）
验证成功 → 保存返回的 data.verified_token
点击登录 → 请求登录接口，携带 account、password、verified_token

路由

安装后自动注册以下路由（前缀可配置）：

方法	路径	说明
GET	/slider-captcha/generate	生成验证码
POST	/slider-captcha/verify	验证验证码
GET	/slider-captcha/image/{token}	图片访问（鉴权）
GET	/slider-captcha/refresh-bg	手动刷新背景图
GET	/slider-captcha/clean-temp	手动清理临时图

若需挂到 /api 下，设置 route_prefix 为 api/slider-captcha。

定时任务

包会自动注册：

每日 00:00：刷新背景图
每小时：清理过期临时图

确保已配置 Laravel 调度器（crontab）：

* * * * * cd /path-to-your-project && php artisan schedule:run >> /dev/null 2>&1

手动命令

# 刷新背景图
php artisan slider-captcha:refresh

# 清理临时图（默认 1 小时前）
php artisan slider-captcha:clean

# 清理 2 小时前的临时图
php artisan slider-captcha:clean --hours=2

API 使用

生成验证码

GET /slider-captcha/generate

响应：

{
  "code": 200,
  "msg": "生成成功",
  "data": {
    "token": "xxx",
    "bg_image_url": "/slider-captcha/image/xxx",
    "slide_image_url": "/slider-captcha/image/xxx",
    "captcha_width": 320,
    "captcha_height": 155,
    "slider_width": 65,
    "slider_height": 65,
    "slide_y": 45
  }
}

slide_y 为拼图块垂直位置，前端需据此设置拼图块的 top 样式。

验证验证码

POST /slider-captcha/verify
Content-Type: application/json

{
  "token": "xxx",
  "puzzle_x": 150,
  "slide_time": 1200,
  "track": [{"x": 0, "y": 0}, ...]
}

验证成功响应（含 verified_token，登录时携带）：

{
  "code": 200,
  "msg": "验证成功",
  "data": {
    "verified_token": "xxx...",
    "puzzle_x": 150,
    "target_x": 150,
    "difference": 0,
    "tolerance": 8
  }
}

登录时校验 verified_token

在登录接口中，要求前端传入 verified_token，并调用包提供的静态方法校验：

use Gong86627\SliderCaptcha\SecureSliderCaptcha;

// 登录方法内
$verifiedToken = $request->input('verified_token');
$verifiedData = SecureSliderCaptcha::consumeVerifiedToken($verifiedToken);

if (!$verifiedData) {
    throw ValidationException::withMessages([
        'captcha' => ['验证码已过期或无效，请重新完成滑动验证'],
    ]);
}

// 可选：校验 IP 一致（config: verify_ip_check）
if (config('slider-captcha.verify_ip_check') && ($verifiedData['ip'] ?? '') !== $request->ip()) {
    throw ValidationException::withMessages([
        'captcha' => ['验证环境异常，请重新验证'],
    ]);
}

// 通过后继续校验账号密码...

前端集成

推荐使用 vue3-slide-verify，拼图形状已兼容。

将 bg_image_url、slide_image_url 拼上你的 API 根路径后传给组件即可。

License

MIT

gong86627 / laravel-slider-captcha

Maintainers

Package info

Statistics

Security