laravel 官方推荐手写 cors 中间件而非第三方包，因其更轻量、可控、可调试；需单独处理 options 预检请求并确保响应无 body、状态码为 200/204，且 access-control-allow-origin 在 withcredentials 时不可为 *。
为什么不用第三方包而直接写中间件
Laravel 本身不内置 CORS 支持，但官方推荐用中间件而非第三方包（如 fruitcake/laravel-cors）来控制跨域行为——尤其在 Laravel 9+ 版本中，该包已停止维护，且其默认配置容易覆盖你对 Access-Control-Allow-Headers 或预检响应的精细控制。
自己写中间件更轻量、可调试、无隐式行为。比如你遇到 405 Method Not Allowed 预检失败，或 Authorization 头被拦截，第三方包往往只靠配置文件兜底，而中间件里你能明确看到每个响应头是否真的被写出。
- 第三方包可能在
Kernel.php中注册了全局中间件，导致非 API 路由也被加了 CORS 头 - 它默认允许所有 Origin，生产环境必须手动关掉，否则存在安全风险
- 对
OPTIONS请求的处理逻辑封装过深，出问题时难以断点追踪
如何手写一个最小可用的 CORS 中间件
运行 php artisan make:middleware HandleCors，然后在 app/Http/Middleware/HandleCors.php 的 handle() 方法里填入以下逻辑：
public function handle($request, Closure $next)
{
$response = $next($request);
// 只对 API 路由生效（可根据需要调整）
if (str_starts_with($request->path(), 'api/')) {
$response->headers->set('Access-Control-Allow-Origin', env('CORS_ALLOW_ORIGIN', '*'));
$response->headers->set('Access-Control-Allow-Methods', 'GET,POST,PUT,PATCH,DELETE,OPTIONS');
$response->headers->set('Access-Control-Allow-Headers', 'Content-Type,Authorization,X-Requested-With');
$response->headers->set('Access-Control-Allow-Credentials', 'true');
$response->headers->set('Access-Control-Max-Age', '3600');
}
return $response;
}
注意：如果前端发的是带凭证（withCredentials: true）的请求，Access-Control-Allow-Origin 就不能是 *，必须指定具体域名，例如 https://your-frontend.com，否则浏览器会直接拒绝响应。
如何正确注册和使用这个中间件
中间件注册位置决定作用范围——别一股脑扔进 $middlewareGroups['api'] 就完事，得看你的路由结构：
- 如果你用的是
Route::prefix('api')+Route::middleware('api')，就把中间件加到$middlewareGroups['api']数组里 - 如果只是部分接口需要跨域（比如登录、上传），就单独绑定：
Route::post('/upload', [UploadController::class, 'store'])->middleware(HandleCors::class) - 不要在
$middleware全局数组里注册，否则 HTML 页面响应也会带上 CORS 头，徒增干扰
另外，Laravel 默认的 api 中间件组里已有 EnsureFrontendRequestsAreStateful::class，它会检查 session 和 token；如果你的跨域请求依赖 session（比如登录态），确保 HandleCors 在它之前执行，否则预检请求可能被 session 中间件拦截并返回 419。
为什么 OPTIONS 请求没进控制器却仍要处理
浏览器发起跨域请求前，会先发一个 OPTIONS 预检请求。它不走 Laravel 的控制器逻辑，而是由中间件链直接响应。所以你的中间件必须能“拦住”这个请求并返回 200，否则后续真实请求根本不会发出。
常见错误是中间件只在 $next($request) 后设置头，但对 OPTIONS 请求来说，$next() 返回的是空响应（因为没匹配到路由），此时你设的头根本没机会生效。
解决方法是在中间件开头判断：
if ($request->isMethod('OPTIONS')) {
return response('', 200)
->header('Access-Control-Allow-Origin', env('CORS_ALLOW_ORIGIN', '*'))
->header('Access-Control-Allow-Methods', 'GET,POST,PUT,PATCH,DELETE,OPTIONS')
->header('Access-Control-Allow-Headers', 'Content-Type,Authorization,X-Requested-With')
->header('Access-Control-Allow-Credentials', 'true');
}
这个分支必须放在 $next() 之前，且返回完整响应，否则预检失败是静默发生的——你只看到控制台报错 No 'Access-Control-Allow-Origin' header，但网络面板里连 OPTIONS 请求都看不到。
真正容易被忽略的点是：预检响应不能有 body，状态码必须是 200 或 204；一旦你在这里返回了 JSON 或重定向，浏览器就会判定跨域策略无效。
