前言本地开发时最常见的画面是Vue 跑在http://localhost:5173PHP 接口跑在http://127.0.0.1:8000浏览器控制台一片红字——has been blocked by CORS policy: No Access-Control-Allow-Origin header is present。于是有人在 PHP 里加了一行header(Access-Control-Allow-Origin: *)页面通了但带上 Cookie 之后又不行了或者接口一旦需要Authorization头预检请求preflight直接 405。跨域问题的麻烦之处在于它不是后端坏了而是浏览器按三个条件同时判断来源是否被允许、是否允许携带凭据、预检请求是否被正确应答。缺任何一个条件请求在浏览器层就被丢掉PHP 那边的日志里可能连一条访问记录都没有。本文先讲清浏览器到底在拦什么再给出 PHP 端可以照抄的响应头写法含预检提前返回然后说明携带 Cookie 时的额外条件最后给出本地开发更省事的方案Vite 代理。示例的最低 PHP 版本是 8.0。一、浏览器在拦什么简单请求与预检请求浏览器把跨域请求分成两类。判断依据是方法 请求头 Content-Type条件简单请求simple request触发预检方法GET/HEAD/POST其余方法PUT/DELETE/PATCH…Content-Typeapplication/x-www-form-urlencoded、multipart/form-data、text/plainapplication/json、text/xml等自定义头无带Authorization、X-Requested-With、自定义头额外动作直接发出读响应时校验 CORS 头先发一个OPTIONS预检也就是说用 axios/fetch 提交 JSON一定会触发预检。预检请求会带上Access-Control-Request-Method和Access-Control-Request-Headers服务器必须用Access-Control-Allow-Methods/Access-Control-Allow-Headers明确答上这些值浏览器才肯发真正的请求。一个容易被忽略的事实是请求其实已经发到服务器了简单请求尤其如此只是响应被浏览器拦下不给 JS 读取。所以后端日志里能看到请求前端却拿不到数据——这常常误导排查方向。二、PHP 端正确写法白名单 预检提前返回先明确原则不要回显任意 Origin也不要用*。维护一个白名单命中才回显并且加上Vary: Origin避免缓存层把 A 站点的响应发给 B 站点。?php // 最低版本PHP 8.0 declare(strict_types1); const ALLOWED_ORIGINS [ http://localhost:5173, http://127.0.0.1:5173, ]; $origin $_SERVER[HTTP_ORIGIN] ?? ; if ($origin ! in_array($origin, ALLOWED_ORIGINS, 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); header(Access-Control-Max-Age: 600); } // 预检请求到此为止不要继续执行业务逻辑 if (($_SERVER[REQUEST_METHOD] ?? GET) OPTIONS) { http_response_code(204); exit; }三个细节必须注意Access-Control-Allow-Origin只能出现一次。如果 nginx 也加了同样的头浏览器会报The Access-Control-Allow-Origin header contains multiple values两个头同时存在等于没配。只在一处加。预检必须提前exit。如果OPTIONS请求继续往下走业务逻辑未登录时就会返回 401浏览器把预检判为失败真正的请求根本不会发出。Access-Control-Allow-Headers要覆盖前端真实发送的所有头。后端漏掉Authorization前端带 token 就直接失败。三、携带 Cookie 或凭据时的三个额外条件只要请求涉及 Cookie、Authorization头或fetch的credentials: include浏览器会切换到凭据模式规则会变得更严Access-Control-Allow-Origin不能是*必须是具体来源且要与当前页面来源完全一致协议、域名、端口一个都不能差http与https、localhost与127.0.0.1都算不同来源服务器必须返回Access-Control-Allow-Credentials: true前端必须显式开启fetch用credentials: includeaxios 用withCredentials: true或在默认配置里统一打开。Cookie 本身还受SameSite与Secure约束。SameSiteLax的 Cookie 不会随跨站请求发送如果前后端是不同站点且确实需要携带 Cookie需要SameSiteNone; Secure而Secure又要求 HTTPS。这也是为什么本地 HTTP 环境下带 Cookie 的跨域经常怎么配都不通——最省事的做法还是下面要说的代理方案。四、本地开发更推荐的做法用 Vite 开发代理跨域限制只在浏览器里存在。开发阶段完全可以让浏览器只跟 Vite 开发服务器打交道由它把/api请求转发给 PHP——对浏览器来说这是同源请求也就根本不存在 CORS。// vite.config.js import { defineConfig } from vite import vue from vitejs/plugin-vue export default defineConfig({ plugins: [vue()], server: { proxy: { /api: { target: http://127.0.0.1:8000, changeOrigin: true, }, }, }, })前端代码里把请求地址改成相对路径即可// 开发环境走 Vite 代理生产环境由 Nginx 反代到 PHP-FPM const api axios.create({ baseURL: /api, withCredentials: true }) const { data } await api.get(/products)后端可以用 PHP 内置服务器起一个最简环境php -S 127.0.0.1:8000 -t public代理方案的额外好处是Cookie 的域、SameSite行为与生产环境一致不用为了开发环境放宽安全设置。生产环境同样推荐同域 反向代理让 CORS 配置彻底消失只在确实需要开放给第三方站点时才配置白名单。常见坑点1.*和凭据同时出现❌header(Access-Control-Allow-Origin: *); header(Access-Control-Allow-Credentials: true);——浏览器直接拒绝报cannot be used with credentials且不管你怎么调前端都不通。 ✅ 回显白名单里命中的具体 Origin。2. 预检没有提前返回❌OPTIONS请求继续走鉴权中间件未登录返回 401/403——浏览器认定预检失败真正的POST压根没发出去排查看起来像后端没收到请求。 ✅if ($method OPTIONS) { http_response_code(204); exit; }放在所有鉴权逻辑之前。3. nginx 与 PHP 各加一份 CORS 头❌add_header Access-Control-Allow-Origin ...;写在 nginx 配置里PHP 里又加一次——响应出现两个同名头浏览器报contains multiple values。 ✅ 只在一个地方加如果历史配置改不掉可以在 PHP 里先header_remove(Access-Control-Allow-Origin)再自己设置。4. 白名单用包含判断❌if (str_contains($origin, localhost))放行——http://evil-localhost.attacker.com也能过。 ✅ 用in_array($origin, ALLOWED_ORIGINS, true)精确匹配比较时区分协议与端口。5.Allow-Headers漏项❌ 只写了Content-Type前端却发了Authorization或X-Requested-With——预检响应与请求头对不上报Request header field authorization is not allowed。 ✅ 把前端所有自定义头列全也可以调试期先回显Access-Control-Request-Headers的值稳定后再收紧成白名单。6.header()之前已有输出❌ 被include的文件开头有 BOM 或空行、调试时先echo了一句——header()报headers already sentCORS 头一个都没生效看起来就像配了没用。 ✅ 用无 BOM 的 UTF-8 保存?php前不留任何字符出口文件结尾不写?必要时在入口ob_start()兜底。7. 把 CORS 当成安全机制❌ 认为加了白名单就没人能调我的接口——CORS 只是浏览器的策略curl、Postman、服务端脚本完全不受影响。 ✅ 该做的鉴权、限流、CSRF 防护一个都不能少CORS 只是让浏览器愿意把响应交给你的前端代码。总结场景推荐做法关键点本地开发推荐Viteserver.proxy转发/api浏览器视角同源无 CORS必须跨域白名单回显 Origin不能用*加Vary: Origin带 Cookie具体 Origin Allow-Credentials: true前端还要withCredentials预检请求提前204返回不要走到鉴权逻辑生产环境同域反向代理让 CORS 配置彻底消失跨域问题的本质是三件事必须同时成立来源被允许、凭据被允许、预检被正确应答。开发阶段用 Vite 代理可以把这三件事一起绕开必须跨域时就按白名单回显、明确列出方法与会话头、预检提前返回这三条来做同时记住 CORS 从来不是安全边界。
前言本地开发时最常见的画面是Vue 跑在http://localhost:5173PHP 接口跑在http://127.0.0.1:8000浏览器控制台一片红字——has been blocked by CORS policy: No Access-Control-Allow-Origin header is present。于是有人在 PHP 里加了一行header(Access-Control-Allow-Origin: *)页面通了但带上 Cookie 之后又不行了或者接口一旦需要Authorization头预检请求preflight直接 405。跨域问题的麻烦之处在于它不是后端坏了而是浏览器按三个条件同时判断来源是否被允许、是否允许携带凭据、预检请求是否被正确应答。缺任何一个条件请求在浏览器层就被丢掉PHP 那边的日志里可能连一条访问记录都没有。本文先讲清浏览器到底在拦什么再给出 PHP 端可以照抄的响应头写法含预检提前返回然后说明携带 Cookie 时的额外条件最后给出本地开发更省事的方案Vite 代理。示例的最低 PHP 版本是 8.0。一、浏览器在拦什么简单请求与预检请求浏览器把跨域请求分成两类。判断依据是方法 请求头 Content-Type条件简单请求simple request触发预检方法GET/HEAD/POST其余方法PUT/DELETE/PATCH…Content-Typeapplication/x-www-form-urlencoded、multipart/form-data、text/plainapplication/json、text/xml等自定义头无带Authorization、X-Requested-With、自定义头额外动作直接发出读响应时校验 CORS 头先发一个OPTIONS预检也就是说用 axios/fetch 提交 JSON一定会触发预检。预检请求会带上Access-Control-Request-Method和Access-Control-Request-Headers服务器必须用Access-Control-Allow-Methods/Access-Control-Allow-Headers明确答上这些值浏览器才肯发真正的请求。一个容易被忽略的事实是请求其实已经发到服务器了简单请求尤其如此只是响应被浏览器拦下不给 JS 读取。所以后端日志里能看到请求前端却拿不到数据——这常常误导排查方向。二、PHP 端正确写法白名单 预检提前返回先明确原则不要回显任意 Origin也不要用*。维护一个白名单命中才回显并且加上Vary: Origin避免缓存层把 A 站点的响应发给 B 站点。?php // 最低版本PHP 8.0 declare(strict_types1); const ALLOWED_ORIGINS [ http://localhost:5173, http://127.0.0.1:5173, ]; $origin $_SERVER[HTTP_ORIGIN] ?? ; if ($origin ! in_array($origin, ALLOWED_ORIGINS, 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); header(Access-Control-Max-Age: 600); } // 预检请求到此为止不要继续执行业务逻辑 if (($_SERVER[REQUEST_METHOD] ?? GET) OPTIONS) { http_response_code(204); exit; }三个细节必须注意Access-Control-Allow-Origin只能出现一次。如果 nginx 也加了同样的头浏览器会报The Access-Control-Allow-Origin header contains multiple values两个头同时存在等于没配。只在一处加。预检必须提前exit。如果OPTIONS请求继续往下走业务逻辑未登录时就会返回 401浏览器把预检判为失败真正的请求根本不会发出。Access-Control-Allow-Headers要覆盖前端真实发送的所有头。后端漏掉Authorization前端带 token 就直接失败。三、携带 Cookie 或凭据时的三个额外条件只要请求涉及 Cookie、Authorization头或fetch的credentials: include浏览器会切换到凭据模式规则会变得更严Access-Control-Allow-Origin不能是*必须是具体来源且要与当前页面来源完全一致协议、域名、端口一个都不能差http与https、localhost与127.0.0.1都算不同来源服务器必须返回Access-Control-Allow-Credentials: true前端必须显式开启fetch用credentials: includeaxios 用withCredentials: true或在默认配置里统一打开。Cookie 本身还受SameSite与Secure约束。SameSiteLax的 Cookie 不会随跨站请求发送如果前后端是不同站点且确实需要携带 Cookie需要SameSiteNone; Secure而Secure又要求 HTTPS。这也是为什么本地 HTTP 环境下带 Cookie 的跨域经常怎么配都不通——最省事的做法还是下面要说的代理方案。四、本地开发更推荐的做法用 Vite 开发代理跨域限制只在浏览器里存在。开发阶段完全可以让浏览器只跟 Vite 开发服务器打交道由它把/api请求转发给 PHP——对浏览器来说这是同源请求也就根本不存在 CORS。// vite.config.js import { defineConfig } from vite import vue from vitejs/plugin-vue export default defineConfig({ plugins: [vue()], server: { proxy: { /api: { target: http://127.0.0.1:8000, changeOrigin: true, }, }, }, })前端代码里把请求地址改成相对路径即可// 开发环境走 Vite 代理生产环境由 Nginx 反代到 PHP-FPM const api axios.create({ baseURL: /api, withCredentials: true }) const { data } await api.get(/products)后端可以用 PHP 内置服务器起一个最简环境php -S 127.0.0.1:8000 -t public代理方案的额外好处是Cookie 的域、SameSite行为与生产环境一致不用为了开发环境放宽安全设置。生产环境同样推荐同域 反向代理让 CORS 配置彻底消失只在确实需要开放给第三方站点时才配置白名单。常见坑点1.*和凭据同时出现❌header(Access-Control-Allow-Origin: *); header(Access-Control-Allow-Credentials: true);——浏览器直接拒绝报cannot be used with credentials且不管你怎么调前端都不通。 ✅ 回显白名单里命中的具体 Origin。2. 预检没有提前返回❌OPTIONS请求继续走鉴权中间件未登录返回 401/403——浏览器认定预检失败真正的POST压根没发出去排查看起来像后端没收到请求。 ✅if ($method OPTIONS) { http_response_code(204); exit; }放在所有鉴权逻辑之前。3. nginx 与 PHP 各加一份 CORS 头❌add_header Access-Control-Allow-Origin ...;写在 nginx 配置里PHP 里又加一次——响应出现两个同名头浏览器报contains multiple values。 ✅ 只在一个地方加如果历史配置改不掉可以在 PHP 里先header_remove(Access-Control-Allow-Origin)再自己设置。4. 白名单用包含判断❌if (str_contains($origin, localhost))放行——http://evil-localhost.attacker.com也能过。 ✅ 用in_array($origin, ALLOWED_ORIGINS, true)精确匹配比较时区分协议与端口。5.Allow-Headers漏项❌ 只写了Content-Type前端却发了Authorization或X-Requested-With——预检响应与请求头对不上报Request header field authorization is not allowed。 ✅ 把前端所有自定义头列全也可以调试期先回显Access-Control-Request-Headers的值稳定后再收紧成白名单。6.header()之前已有输出❌ 被include的文件开头有 BOM 或空行、调试时先echo了一句——header()报headers already sentCORS 头一个都没生效看起来就像配了没用。 ✅ 用无 BOM 的 UTF-8 保存?php前不留任何字符出口文件结尾不写?必要时在入口ob_start()兜底。7. 把 CORS 当成安全机制❌ 认为加了白名单就没人能调我的接口——CORS 只是浏览器的策略curl、Postman、服务端脚本完全不受影响。 ✅ 该做的鉴权、限流、CSRF 防护一个都不能少CORS 只是让浏览器愿意把响应交给你的前端代码。总结场景推荐做法关键点本地开发推荐Viteserver.proxy转发/api浏览器视角同源无 CORS必须跨域白名单回显 Origin不能用*加Vary: Origin带 Cookie具体 Origin Allow-Credentials: true前端还要withCredentials预检请求提前204返回不要走到鉴权逻辑生产环境同域反向代理让 CORS 配置彻底消失跨域问题的本质是三件事必须同时成立来源被允许、凭据被允许、预检被正确应答。开发阶段用 Vite 代理可以把这三件事一起绕开必须跨域时就按白名单回显、明确列出方法与会话头、预检提前返回这三条来做同时记住 CORS 从来不是安全边界。
