搞跨域调试这事十个人里有九个第一反应是“后端接口有问题”后端那边拿 curl 一打又能通两边一对质就僵住了。我见过太多次这种场面前端在 localhost:8080 跑项目接口在 api.example.com控制台一片红Network 面板里请求状态写着 CORS error而后端日志里其实每一次请求都进来了甚至数据库都写进去了。问题的根子基本不在“请求有没有到达后端”而在“浏览器的安全机制允不允许前端读到这次响应”。这篇文章把从 0 到定位问题的完整链路写清楚先讲明白同源策略到底拦的是什么然后给一套用控制台和 curl 逐层缩小范围的排查方法最后落到 PHP 代码的可直接套用方案。带 Cookie、自定义头、多域名白名单这些进阶场景也会一并处理源码都贴在下面。1. 先搞清楚浏览器为什么拦这个安全机制其实很讲道理1.1 同源、跨域与CORS的本质关系所谓“同源”指的是协议、域名、端口三者完全一致。只要有一个对不上就是跨域。举例来说http://localhost:8080请求http://api.example.com域名不同跨域。https://www.example.com请求http://www.example.com协议不同跨域。http://www.example.com:8081请求http://www.example.com:8080端口不同跨域。浏览器会有这个限制核心目的是防止一个网页在你不知情的情况下借用你的登录凭证去读取另一个网站的敏感数据。设想一下如果你正在某个网银页面登录着又打开了另一个网页那个网页里的脚本偷偷向网银接口发请求、读取余额并回传如果没有同源策略后台数据等于裸奔。CORS跨域资源共享就是服务端发给浏览器的一张“临时通行证”。它是在 HTTP 响应里通过Access-Control-Allow-*这组头告诉浏览器这个来源的响应允许那个页面来读。说穿了跨域问题的本质不是网络通了没有而是响应头上有没有那张通行证。1.2 简单请求和非简单请求为什么有的请求被拦、有的不拦我把这组关系用一个核心原则概括请求越“普通”检查越松请求越“特殊”检查越严。只要同时满足以下条件就是“简单请求”请求方法为 GET、HEAD、POST 中的一个请求头只有几个浏览器认为安全的头比如 Accept、Accept-Language、Content-Type 且 Content-Type 只能是application/x-www-form-urlencoded、multipart/form-data、text/plain三者之一请求里没有自定义头如 Authorization、X-Requested-With、X-Token。简单请求的处理方式浏览器直接发出业务请求响应回来后会检查响应头。如果缺少合法的Access-Control-Allow-Origin浏览器会把响应锁住JS 拿不到数据控制台报 CORS 错误。一旦请求用了 PUT、DELETE或者Content-Type: application/json或者带了自定义请求头它就成了“非简单请求”。浏览器会先发一个 OPTIONS 预检请求去问服务端我稍后要发一个这样的请求你允许吗服务端必须用正确的Access-Control-Allow-*头回答预检通过后浏览器才会发出真正的业务请求。请求类型常见触发场景浏览器行为简单请求GET 公开接口、POST 表单直接发请求响应被拦截时 JS 读取失败非简单请求预检JSON 请求体、自定义头、PUT/DELETE先发 OPTIONS 询问许可通过后再发真正的请求这个区分在排查时很关键因为预检失败和简单请求失败报错文案、Network 面板里的表现完全不一样。1.3 浏览器拦的是“读”不是“发”很多人排查跨域的第一步就走错了方向——以为跨域了请求根本没发出去。这里要澄清一个事实请求发得出去服务端也处理得完响应也真实地回到了浏览器只是浏览器按同源策略不把响应内容交给页面的 JS。这个认知能解释很多怪现象比如后端日志里有请求记录、接口里甚至产生了数据变更前端却一直报跨域错误。不是后端没收到是收到了但前端读不到。所以在最开始定位的时候不要反复在后端日志里找“请求没进来”的证据那是死胡同。正确的做法是直接去看响应头里有没有那张“通行证”。2. 一套可复用的定位链路从报错文案到根因2.1 控制台三种常见报错分别对应什么问题控制台里 CORS 相关报错看起来五花八门但核心文案翻来覆去就几类这里按“看到什么就怀疑什么”的思路整理。报错关键文案含义排查方向No Access-Control-Allow-Origin header is present响应里根本没有 CORS 头后端没设置或设置了但没生效must not be the wildcard * when credentials mode is include用了*通配符同时又要求带凭证带凭证的场景必须返回具体 OriginResponse to preflight request doesnt pass access control checkOPTIONS 预检没通过服务端没有正确响应 OPTIONS或路由拦截了它另外要提醒一句“Failed to fetch”这个报错经常和 CORS 混在一起但它也可能是网络失败或后端 5xx。所以在报错里看到“Failed to fetch”不要条件反射地认定一定是跨域要结合 Network 面板看真实状态码。2.2 Network 面板告诉你请求到底经历了什么打开浏览器的开发者工具切到 Network筛选出接口请求重点看两条信息。第一是看有没有 OPTIONS 请求。如果某个 POST 请求前面跟了一个 OPTIONS 请求说明这是非简单请求的预检过程。此时预检请求的状态码如果落在 200、204 都还算正常如果看到 404、405那基本可以断定是服务端路由层把 OPTIONS 拒绝了。第二是看响应头。点开请求详情找 Headers 区域看Access-Control-Allow-Origin有没有出现。如果请求是简单请求Network 里只有一个请求而响应头里没有 CORS 头问题就直接锁定在后端响应头缺失。这里有个小技巧把 Network 面板的状态列先打开跨域失败的请求状态通常会显示(failed) net::ERR_FAILED配合响应头信息能很快判断出到底是“预检没通过”还是“响应头缺失”还是“后端本身报错”。2.3 用 curl 把浏览器从链路里摘出去浏览器会隐藏跨域响应的内容这对排查非常不友好。curl 不执行同源策略能直接看到完整响应头和响应体是定位 CORS 问题最趁手的工具。关键是一定要手动带上Origin头否则它体会不到浏览器的视角。先模拟一次简单请求同时看响应头curl -i http://api.example.com/v1/user/login \ -H Origin: http://localhost:8080-i的作用是显示响应头。输出里如果能找到Access-Control-Allow-Origin: *说明后端这块配置是通的如果看到响应体正常返回但响应头里没有 CORS 头说明问题就出在 PHP 代码层。再模拟一次预检请求curl -i -X OPTIONS http://api.example.com/v1/user/login \ -H Origin: http://localhost:8080 \ -H Access-Control-Request-Method: POST \ -H Access-Control-Request-Headers: Content-Type注意Access-Control-Request-Method和Access-Control-Request-Headers是预检请求特有的请求头服务端会参考它们来决定返回哪些Allow-Methods、Allow-Headers。curl 里把这两个头上齐了才能完整复现浏览器的预检过程。2.4 锁定到 PHP 层确认 header 到底有没有输出用 curl 排除浏览器干扰之后基本就走到了分岔口响应头里有 CORS 头那是浏览器侧或服务器侧的叠加问题响应头里没有 CORS 头那就是 PHP 代码问题。到了 PHP 层大多数情况是header()调用没执行到、执行顺序晚于业务输出或者调用后被其他逻辑覆盖。可以临时用下面这行代码把执行现场打出来if (headers_sent($file, $line)) { error_log(headers already sent at {$file}:{$line}); }headers_sent()如果返回 true说明在某一行已经有输出后面的header()要么触发告警要么不生效。这行诊断代码建议放在入口文件的最前方能一次性排除大量“我明明写了 header 却没用”的困惑。定位到这里就可以带着确切结论进入修复阶段了。3. PHP 跨域响应的最小实现与完整源码3.1 三行 header 解决掉九成场景对于公开接口最朴素的方案就是三行 header放在入口文件、路由分发之前header(Access-Control-Allow-Origin: *); header(Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS); header(Access-Control-Allow-Headers: Content-Type, Authorization, X-Requested-With);这三个头各自的作用Allow-Origin告诉浏览器允许哪个来源读取响应*表示所有来源Allow-Methods声明接口允许哪些请求方法Allow-Headers声明允许前端带哪些自定义请求头。只做这三行GET、POST 去请求公开接口基本就通了。但有两个隐患一是带 Cookie 或登录态时不能用*这一点后面单独讲二是如果前端发了 DELETE、PUT 或 JSON 请求体会触发预检而这个写法没有主动处理 OPTIONS 请求很多框架路由会把 OPTIONS 当成未定义路由返回 404。所以更完整的方案要加上预检处理。3.2 一个可以直接用的 CorsHelper 类我实际项目里比较喜欢把跨域逻辑收敛成一个工具类在入口处调用一次后面所有控制器都不需要再关心头信息。下面这份源码覆盖了白名单、凭证和预检请求是相对完整的一个版本?php class CorsHelper { // 允许的来源白名单留空表示允许所有来源 private static array $allowedOrigins [ http://localhost:8080, https://admin.example.com, ]; private static string $allowedMethods GET, POST, PUT, PATCH, DELETE, OPTIONS; private static string $allowedHeaders Content-Type, Authorization, X-Requested-With, X-Token; private static int $maxAge 86400; public static function init(): void { $origin $_SERVER[HTTP_ORIGIN] ?? ; // 白名单非空且命中时返回具体 Origin并放开 Credentials if (self::$allowedOrigins ! [] in_array($origin, self::$allowedOrigins, true)) { header(Access-Control-Allow-Origin: . $origin); header(Vary: Origin); header(Access-Control-Allow-Credentials: true); } else { header(Access-Control-Allow-Origin: *); } header(Access-Control-Allow-Methods: . self::$allowedMethods); header(Access-Control-Allow-Headers: . self::$allowedHeaders); // 预检请求直接结束不再往下走业务路由 if (($_SERVER[REQUEST_METHOD] ?? ) OPTIONS) { header(Access-Control-Max-Age: . self::$maxAge); http_response_code(204); exit; } } }使用方式是在入口文件里、任何输出发生之前调用一次require __DIR__ . /CorsHelper.php; CorsHelper::init(); // 之后才是路由分发这个类里有几个容易被忽略的点一是Vary: Origin它告诉中间缓存节点“同一个 URL 的响应会根据 Origin 不同而变化”避免带 Cookie 的响应被错误地复用到其他来源二是预检请求返回 204 而不是 200因为 204 No Content 语义更准确也能让一些框架少做无意义的响应组装。3.3 在 Laravel、ThinkPHP 和原生 PHP 里的接入位置方式一原生 PHP在 index.php 的最靠前位置调用这个类保证在路由解析之前 CORS 头就已经放出去了。方式二Laravel推荐用中间件注册到全局中间件里。这样所有请求都会经它过一遍不会漏路由?php namespace App\Http\Middleware; use Closure; use Illuminate\Http\Request; use Symfony\Component\HttpFoundation\Response; class CorsMiddleware { public function handle(Request $request, Closure $next): Response { if ($request-isMethod(options)) { $response response(, 204); } else { $response $next($request); } $origin $request-headers-get(Origin, ); $allowedOrigins [http://localhost:8080, https://admin.example.com]; if (in_array($origin, $allowedOrigins, true)) { $response-headers-set(Access-Control-Allow-Origin, $origin); $response-headers-set(Vary, Origin); $response-headers-set(Access-Control-Allow-Credentials, true); } $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, X-Token); $response-headers-set(Access-Control-Max-Age, 86400); return $response; } }然后把这个中间件加进app/Http/Kernel.php的$middleware全局数组或者在bootstrap/app.php里按项目版本注册。方式三ThinkPHP如果用的是 ThinkPHP 6框架本身内置了AllowCrossDomain中间件在中间件配置文件里注册即可不用自己写类。它能处理全站跨域大多数项目直接启用就够了。3.4 OPTIONS 预检的正确处理姿势预检请求本质上是浏览器的一次“试探”。它通过Access-Control-Request-Method和Access-Control-Request-Headers两个头告诉服务端“我马上要发的方法和头是什么”服务端响应的Access-Control-Allow-Methods和Access-Control-Allow-Headers必须覆盖这些值预检才算通过。一旦预检响应里缺失这两个头或者方法列表里没有前端要用的方法浏览器就会中止后续的真实请求。这是“明明后端有接口前端却发不出请求”的一大原因而且表现得很迷惑——Network 里只有 OPTIONS没有后面的 POST。Access-Control-Max-Age的作用是告诉浏览器“你可以把这次预检结果缓存 N 秒期间不需要再发 OPTIONS”。生产环境设一个 8640024小时能显著减少预检请求次数性能上更友好。但调试阶段我建议把它改成 0 或者干脆删掉因为浏览器一旦缓存了旧的预检结果你后端的跨域配置改了也半天不生效排查时非常误事。提示预检请求本身不应该携带业务逻辑服务端在收到 OPTIONS 后直接返回 204 并结束请求是最稳妥的做法。如果让它继续向下执行到业务控制器可能会因为路由不匹配而返回 404反而把预检搞失败。4. 带凭证、自定义头和多域名进阶场景的完整处理4.1 带 Cookie 或登录态时的三条件缺一不可如果接口要识别当前登录用户前端发起跨域请求时通常需要携带浏览器里的 Cookie。这种情况下CORS 配置必须满足三个条件缺一个都会报错。第一Access-Control-Allow-Origin不能是*必须返回明确的来源地址。浏览器之所以一刀切禁止通配符和凭证同时出现是因为*相当于对任何站点开放再配合 Cookie 会把登录凭证暴露给不可信的来源。第二响应头里必须加上Access-Control-Allow-Credentials: true。第三前端在发起请求时必须带上凭证。fetch 的写法是加credentials: includeaxios 的写法是withCredentials: true。$origin $_SERVER[HTTP_ORIGIN] ?? ; $allowedOrigins [http://localhost:8080, https://admin.example.com]; if (in_array($origin, $allowedOrigins, true)) { header(Access-Control-Allow-Origin: . $origin); header(Vary: Origin); header(Access-Control-Allow-Credentials: true); } header(Access-Control-Allow-Methods: GET, POST, PUT, PATCH, DELETE, OPTIONS); header(Access-Control-Allow-Headers: Content-Type, Authorization, X-Requested-With);这里还有一层容易被忽略的坑如果前端用了withCredentials: true但后端没有返回Access-Control-Allow-Credentials: true浏览器会直接拒绝报错文案就是前面提到的那个通配符报错。很多项目在公开接口阶段用的是*后来加了登录功能只改了前端忘了动后端于是“登录接口跨域失败、其他接口没事”的怪现象就出现了。4.2 自定义请求头比如 Token该怎么配现在的接口大多用 Token 做鉴权常见的是Authorization: Bearer xxx也有项目习惯自定义X-Token。这些都属于自定义请求头一旦前端带上它们请求就会升级为非简单请求触发预检。这时候Access-Control-Allow-Headers必须包含前端实际发送的头名称。注意这个头是逗号分隔的名字要精确匹配比如你允许了Authorization, Content-Type前端又额外带了个X-Token预检还是会失败因为列表里没有它。生产环境我建议按需精确列出头而不是在代码里临时回显Access-Control-Request-Headers的值。后者虽然一劳永逸但等于把自定义头的开关完全交给请求方属于不必要的放开。按需列出还有个好处排查的时候看到列表就能立刻知道这个接口默认收哪些头团队协作时信息也更明确。4.3 多域名白名单怎么做才安全接口如果同时服务管理后台、官网和本地开发环境就不能用单一的*得做一个可控的白名单。我见过最简单的方案是数组加 in_array 判断也是我推荐的方式$allowedOrigins [ http://localhost:8080, https://www.example.com, https://admin.example.com, ]; $origin $_SERVER[HTTP_ORIGIN] ?? ; if (in_array($origin, $allowedOrigins, true)) { header(Access-Control-Allow-Origin: . $origin); }这里有一个值得注意的细节判断来源时尽量用完整的Origin字符串精确匹配不要图省事只比对 Host更不要拿Referer做判断。某个来源的明文形式、带的端口、下划线域名等都有可能被前端可控地改动精确匹配能最大限度避免白名单被绕过。如果非要支持泛域名比如*.example.com这种需求我不建议用简单的字符串拼接更稳的是做一次严谨的正则匹配并且在匹配前用parse_url取出 Host 部分。这种需求比较少见真遇到了优先考虑在配置中心维护一份完整域名清单比在代码里写复杂的匹配逻辑更不容易出错。5. 那些“明明设了却不生效”的深坑5.1 header() 调用失败输出提前和 BOM 是元凶最常见的“代码写着跨域头实际请求里没有”的原因就是header()调用之前已经有输出。PHP 的响应头必须在任何输出之前发送一旦页面输出了几个字符后续的header()就会直接失败日志里往往只有一条 PHP Warning很多人根本没注意到。这个“输出”可能是入口文件里无意加的一个空格更多时候是 UTF-8 BOM 字节。用某些编辑器保存 PHP 文件时文件开头会被写入几个不可见字符它们不属于?php的内容但浏览器或命令行都会把它当作输出。排查办法很简单用十六进制编辑器看一眼文件头三个字节如果是EF BB BF就是 BOM另存为 UTF-8 无 BOM 格式即可。另外PHP 的output_buffering配置会影响这里的行为。开启了输出缓冲header()能勉强兜住不报错但缓冲也有上限业务逻辑一旦输出大量内容再调header()一样可能出错。所以在架构上跨域头一定要放在请求处理的最早期而不是在控制器里。5.2 框架路由把 OPTIONS 请求拦截了第二个高频深坑是框架路由对 OPTIONS 不友好。拿 Laravel 举例如果你在控制器里写好了 CORS 逻辑但只是注册了Route::post浏览器发来的预检请求是 OPTIONS 方法它根本匹配不上这个路由直接被框架返回 405。405 响应里一般也没有 CORS 头于是预检必然失败。这也是我强烈建议把 CORS 处理做成入口级中间件而非控制器内代码的原因。入口中间件在路由匹配之前就能判断并响应 OPTIONS完全不依赖具体路由是否存在。ThinkPHP 的内置AllowCrossDomain中间件能在你不需要知道任何路由细节的情况下处理完整跨域想自己实现时照这个思路做准没错。5.3 服务器层级的头叠加Nginx 或 Apache 的双重 CORS有的项目为了图省事直接把跨域头写在 Nginx 配置里PHP 代码里又设置了一份。结果就可能出现响应头里有两个Access-Control-Allow-Origin或者一个被另一个覆盖。浏览器收到重复的 CORS 头时处理规则和单值不一样很容易直接判定不通过。Nginx 还有一个隐蔽点add_header默认不会加到非 2xx/3xx 响应上。你的接口在正常 200 时携带了 CORS 头一旦业务报错返回 400 或 500服务端的 CORS 头就消失了前端看到的就变成 CORS 错误后端日志里却明明是业务错误。这种信息错位会浪费大量排查时间。如果要把 CORS 放在 Nginx 层写add_header时记得带上always关键字add_header Access-Control-Allow-Origin $http_origin always; add_header Access-Control-Allow-Methods GET, POST, PUT, DELETE, OPTIONS always; add_header Access-Control-Allow-Headers Content-Type, Authorization, X-Requested-With always;我的建议是“二选一”要么全交给 PHP 入口统一管理要么全交给 Nginx 统一管理不要在两层都配。两层都配一旦规则不一致排查起来加倍痛苦。5.4 浏览器缓存了预检结果改完代码却像没改这个坑非常容易误导人。你把后端代码改了用 curl 验证新配置已经生效刷新浏览器却发现还是老报错。原因大概率是浏览器缓存了之前的 OPTIONS 预检响应Access-Control-Max-Age设得越大缓存时间越长。调试期间把Max-Age设成 0 或者直接不输出能避免这个信息差。真出现缓存问题可以用无痕窗口、硬刷新CtrlShiftR或者去开发者工具的 Application 面板里清除站点数据。等调试完毕再把它调回一个合理值比如 3600 或 86400给生产环境减负。5.5 只给成功分支加 CORS 头报错时前端一片茫然最后一个很隐蔽的习惯性错误有人把 CORS 头写在了业务逻辑的成功分支里比如登录成功才返回跨域头但登录失败、参数校验失败这种分支没写。后果是接口正常运行没问题一旦业务报错响应头里没有 CORS 头浏览器直接把错误响应拦了前端看到的是“跨域错误”后端看到的却是明确的 400。你设身处地想一下这个场面前端说跨域后端查了日志发现是参数错误两边信息完全没法对上。这类问题唯一的解法就是把 CORS 头放到所有业务逻辑之前对任何响应一视同仁地输出。我在代码里永远不会把跨域处理的职责散落到各个控制器的分支里入口处统一处理后端报什么错浏览器就能看到什么错这才是调试时该有的状态。6. 前端侧几个配合细节跨域调试不能只盯着后端前端几个小设置也会影响最终结果。fetch 默认的credentials是same-origin跨域请求如果需要带 Cookie 会话必须显式写成fetch(url, { credentials: include })。axios 则需要设置axios.defaults.withCredentials true。这两处不写即使后端把 CORS 头配齐全浏览器也不会把 Cookie 一起带上。另外如果是本地开发阶段很多项目会用 Vite 或 webpack 的代理把/api前缀转发到目标服务器这样请求变成了“同源”跨域问题会被掩盖。我的态度是代理可以作为日常开发的提速手段但生产部署前必须验证一遍真实环境下的跨域配置否则等上线时才发现问题排错成本就高了。一个调试阶段比较实用的组合是curl 负责验证后端配置Network 面板负责看清浏览器行为改完代码后立刻硬刷新。三者配合大部分 CORS 问题都能在十分钟内定位到具体那一层。我自己最顺手的方式始终是把跨域头固定在入口或中间件层统一输出不散落在控制器里这样既保证了成功和报错响应都有一致的行为也减少了两边扯皮的机会。
