中间件不是“加个装饰”，而是请求进控制器前、响应发给客户端前的必经关卡；没注册就用会直接报 Class auth does not exist，漏掉 return $next($request) 会导致请求卡死。
怎么创建中间件才不会出错
用 Artisan 命令生成最稳妥：php artisan make:middleware CheckAge。它会在 app/Http/Middleware/ 下生成标准结构文件，自动带好 handle() 签名（Laravel 9+ 是 public function handle(Request $request, Closure $next): Response）。
- 别手动写类——容易漏
use、错签名、少return - 函数名必须是
handle，且参数顺序不能乱：前两个固定是$request和$next，多参数从第三个起传入 - 如果要支持路由传参（如
middleware('role:admin,editor')），handle()必须声明对应形参，比如handle($request, $next, $roles)
注册中间件时三种方式的区别和坑
注册位置决定作用范围和性能影响，混用会引发意料外的行为。
-
$middleware（全局）：写在app/Http/Kernel.php的$middleware数组里，对所有 HTTP 请求生效。适合TrustProxies、CheckForMaintenanceMode这类影响整个应用网络或生命周期的逻辑。别把auth或throttle放这儿，否则 API 和静态资源也得过登录检查 -
$routeMiddleware（路由别名）：注册到$routeMiddleware数组，如'age' => \App\Http\Middleware\CheckAge::class，然后在路由中用->middleware('age')。这是最常用的方式 -
Route::middleware([...])->group(...)（分组）：适用于一组有共性需求的路由，比如所有后台接口都要auth+verified，比每个路由单独写更清晰
auth 中间件为什么在 API 路由里总跳 302
因为默认 auth 中间件绑定的是 web guard，依赖 session 和 Cookie。API 请求通常无会话上下文，未认证时框架会执行重定向逻辑，返回 302 到 /login，而不是 JSON 错误。
Laravel Cloud
下载
Laravel Cloud（cloud.laravel.com）。此技能用于处理所有 Laravel Cloud 请求，包括搜索和读取数据。只要任务涉及 Laravel Cloud，即使用此技能。
- API 场景必须换 guard：改用
auth:sanctum或auth:api，并确认config/auth.php中对应 guard 的driver（如sanctum）和provider配置正确 - 确保请求头含
Authorization: Bearer {token}，且前端未设置withCredentials: true（会触发 CORS 预检失败） - 常见错误现象包括
419 Page Expired（CSRF 拦截）、Unauthenticated（token 缺失或过期）、302 Found（仍走 web guard）
日志中间件为什么记不准耗时或写不进日志
耗时统计必须在 $next($request) 之后获取响应对象；日志写入若用同步文件操作，在高并发下极易因文件锁阻塞主线程。
- 正确姿势：
$start = microtime(true); $response = $next($request); $duration = round((microtime(true) - $start) * 1000); - 记录日志必须用 Laravel 日志通道，如
Log::info("Request {$request->fullUrl()} took {$duration}ms", [...]);，而非file_put_contents() - 别在中间件里访问数据库或 Session 做耗时操作——执行时机早于控制器，但某些服务（如 session driver）可能尚未完全初始化，易出错
中间件真正的复杂点不在写法，而在执行时机与副作用的耦合：比如 StartSession 在请求阶段启动会话、响应阶段持久化；EnsureTenantAccess 往全局上下文写租户 ID，后续所有模型查询都依赖它——一旦这个中间件被跳过或顺序错位，整个数据隔离就崩了。
