Laravel跨域问题解决与CORS配置教程

本文深入解析了 Laravel 中跨域（CORS）问题的本质与最佳实践，强调官方推荐手写轻量、可控、可调试的自定义中间件而非依赖已停止维护的第三方包；文章不仅指出常见陷阱——如带凭证请求时 `Access-Control-Allow-Origin` 不能为 `*`、OPTIONS 预检请求必须单独拦截并返回无 body 的 200/204 响应、中间件注册位置影响作用范围及执行顺序（需置于 session 相关中间件之前），还提供了开箱即用的最小化实现代码和精准配置建议，帮助开发者彻底避开静默失败、安全风险与调试困境，真正掌握跨域治理的主动权。

为什么不用第三方包而直接写中间件

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 或重定向，浏览器就会判定跨域策略无效。

本篇关于《Laravel跨域问题解决与CORS配置教程》的介绍就到此结束啦，但是学无止境，想要了解学习更多关于文章的相关知识，请关注golang学习网公众号！