<p>throttle:api 中间件未生效的根本原因是缓存驱动不支持原子操作、by() 值不稳定或中间件顺序错误；必须使用 redis/database 缓存、规范化 by() 返回值、确保 throttle:api 在 auth 中间件之后执行，并透传 X-RateLimit-* 响应头。</p>
throttle:api 中间件为什么没生效
因为 throttle:api 不是开箱即用的魔法开关，它依赖两个前提：策略已注册、缓存驱动支持原子操作。常见失效场景是开发环境用 array 或 file 缓存驱动——它们不支持 TTL 和并发计数，Limit::perMinute() 会静默退化，$limiter->remaining() 返回 -1，所有请求都算“超限”或“永远不超限”，毫无规律。
必须确认 CACHE_DRIVER 是 redis（生产）或至少 database（本地调试），并在 .env 中显式设置：
CACHE_DRIVER=redis
同时检查 Redis 连接是否正常：php artisan tinker 里执行 cache()->put('test', 'ok', 10) 能否成功写入。
- 别在
web中间件组里用throttle:api—— session 和 auth 中间件顺序不对，$request->user()拿不到，by()的值变成null，所有请求挤进同一个桶 -
throttle:api必须和api路由组或显式auth:sanctum等认证中间件搭配，否则$request->user()?->id恒为null - 如果用了反向代理（Nginx / Cloudflare），
$request->ip()拿到的是代理 IP，得配好App\Http\Middleware\TrustProxies，否则限流对象错乱
RateLimiter::for() 里 by() 的值怎么写才安全
by() 决定“谁共享同一份配额”，但它的参数必须是稳定、非空、无特殊字符的字符串。直接裸用 $request->user()?->id 或 $request->ip() 很危险：未登录用户时前者为 null，IPv6 地址可能含冒号或方括号，都会导致缓存 key 异常或命中失败。
正确写法是始终做空合并 + 标准化处理：
return Limit::perMinute(60)->by($request->user()?->id ?? 'guest_'.str_replace([':', '[', ']'], '_', $request->ip()));
- 登录用户用
$request->user()->id，未登录统一打上guest_XXX前缀，避免和真实 ID 冲突 - IP 地址要过滤掉非法字符，
str_replace()比正则更轻量；若需兼容 IPv6，也可用$request->getClientIp()（已去代理头） - 绝对不要用
auth()->id()替代$request->user()?->id—— 前者在 request 生命周期早期可能还没解析完认证状态，返回null的概率更高
throttle:60,1 和 throttle:api 的根本区别
throttle:60,1 是硬编码规则，走 Laravel 默认的 ThrottleRequests 实现，key 固定为 throttle_'.$request->ip().'_'.$routeName（或加 by=id 后缀），无法复用自定义逻辑；而 throttle:api 是命名策略，触发的是你在 RouteServiceProvider::configureRateLimiting() 里写的闭包，能读请求、判角色、动态选配额。
这意味着：
- 写
throttle:60,1就别指望它识别$request->user()—— 它压根不进你的闭包 - 想按 VIP 角色升配额？只能走
throttle:api+ 自定义策略，throttle:100,1,by=id这种写法只是按模型 ID 限流，不会自动读isVip()属性 -
throttle:global是无效写法，框架没实现这个类型，写了等于没写，日志里搜不到对应 key
429 响应里缺少 X-RateLimit-* 头怎么办
不是配置漏了，而是你覆盖了 Laravel 原生的异常响应格式。比如在 app/Exceptions/Handler.php 的 render() 方法里，对所有 Exception 统一返回 JSON，却没手动透传 ThrottleRequestsException 的响应头。
修复方法是在 render() 中单独处理该异常：
if ($exception instanceof \Illuminate\Routing\Exceptions\ThrottleRequestsException) {
return response()->json(['message' => 'Too many requests'], 429)
->header('X-RateLimit-Limit', $exception->getHeaders()['X-RateLimit-Limit'] ?? 0)
->header('X-RateLimit-Remaining', $exception->getHeaders()['X-RateLimit-Remaining'] ?? 0)
->header('Retry-After', $exception->getHeaders()['Retry-After'] ?? 0);
}- 别用
response()->json(...)->withHeaders(...)，withHeaders()不支持重复 header，而X-RateLimit-*是多个独立 header - 前端依赖这些 header 做重试控制，缺失会导致无限轮询或 UX 断层
- 如果用了 Sanctum 或 Passport，确保
throttle:api在auth:sanctum之后执行，否则认证失败前就触发限流，header 来不及注入
实际跑通的关键不在“写多少策略”，而在 cache 驱动是否真正在用 Redis、by() 的值是否全程可控、以及异常响应是否把原生 header 透出去——这三处任一出问题，限流就从防护变成幻觉。
