Webman限流中间件需驱动、配置、路由三者对齐才生效；全局中间件须注册在''键下，分组路由需对应键名，Redis驱动须手动配置且确保连接有效，memory驱动仅适用于单进程开发。
Webman 限流中间件不是加了就自动生效的，得看驱动、配置、路由注册这三处是否对齐；用错驱动或漏配中间件注册，429 响应根本不会出现。
限流中间件没反应？先检查 config/middleware.php 是否注册正确
全局中间件和分组中间件注册方式不同，但都必须显式写入数组，不能只装包不启用。
- 全局中间件要放在
''键下（空字符串，不是'web'或'api'），例如：'' => [Tinywan\LimitTraffic\Middleware\LimitTrafficMiddleware::class] - 若只想限某类接口，比如所有
/api/路由，得在'api'键下注册，且确保config/route.php中该分组确实用了Route::group('/api', ...) - 使用官方
webman/rate-limiter时，中间件类名是Webman\RateLimiter\Middleware\RateLimiterMiddleware，别和 Tinywan 的混淆 - 中间件类不存在或命名空间拼错，Webman 启动时不会报错，但请求完全绕过限流逻辑
Redis 驱动失效？确认 rate-limiter 组件是否启用对应驱动
webman/rate-limiter 默认用 memory 驱动，单进程有效，多 worker 时计数不共享——这就是为什么本地测试正常、上线后限流“失灵”的常见原因。
- 必须手动在
config/plugin/webman/rate-limiter/app.php中指定驱动：'driver' => 'redis'（或'apcu'） - 选
redis驱动时，需确保config/redis.php已正确定义连接，并且webman/rate-limiter能读到它；组件不复用 Laravel 风格的 Redis 实例，它自己 new Redis() - 用
apcu驱动需确认 PHP 启用了 APCu 扩展（php -m | grep apcu），且未运行在 CLI SAPI 下（APCu 在 CLI 默认禁用） -
memory驱动仅适合开发调试，生产环境务必切走
限流规则不触发？重点核对路由匹配路径与中间件绑定粒度
中间件只对它绑定的路由生效，而 Webman 的路由匹配是精确前缀匹配，不是正则或通配符。
立即学习“PHP免费学习笔记（深入）”；
- 若在
Route::group('/admin', ...)上绑定了限流中间件，但实际访问的是/admin/user/list，没问题；但访问/adminx就完全不触发 - 注解限流（
@RateLimiter）只对控制器方法生效，且要求控制器继承Webman\Controller，否则注解被忽略 - 中间件内默认按
$request->getUri()->getPath()计数，不带 query string；如需区分参数（如/api/data?id=1和/api/data?id=2），得重写getIdentifier()方法 - 测试时别用
curl http://localhost:8787/直连，要走 Nginx 反代——否则$_SERVER['REMOTE_ADDR']可能是127.0.0.1，所有请求被当成同一 IP 计数
响应头缺失 X-Rate-Limit-*？确认中间件返回逻辑是否被覆盖
限流中间件默认会在响应中注入 X-Rate-Limit-Limit、X-Rate-Limit-Remaining 等 header，但这些 header 很容易被后续中间件或控制器 response 覆盖。
- 检查是否在其他中间件里调用了
$response->withHeader()或直接 new Response()，这会丢弃前面中间件设置的 header - 官方
rate-limiter中间件只在拒绝请求（429）时写 header；允许通过的请求，header 不写入——这不是 bug，是设计如此 - Tinywan 版本默认对所有请求（包括放行的）都写 header，但前提是没提前 return response；如果控制器里写了
return json([...])，header 就没了 - 调试时可用
var_dump($response->getHeaders())在中间件末尾打印，确认 header 是否生成成功
真正难调的不是“怎么加限流”，而是“为什么加了没效果”——多数问题出在驱动选择与路由绑定的细节上，尤其是多 worker + memory 驱动这种组合，表面正常，压测时才暴露计数漂移。
