PHP框架中怎么解决API跨域(CORS)问题

向北走

发布时间：2026-09-20| 5人浏览过

原创

PHP框架中的 API 出现跨域问题，通常不需要修改前端来“绕过”，正确做法是在 API 服务端统一配置 CORS 响应头，并让框架能够正确处理浏览器发送的 OPTIONS 预检请求。实际项目中最好把这部分逻辑放进全局中间件或 API 中间件，而不是在每个控制器里重复调用 header()。

处理时需要重点确认四件事：允许哪些来源访问、允许哪些 HTTP 方法、允许哪些请求头，以及是否允许携带 Cookie 等凭证。只要这几项与前端实际请求一致，大多数 PHP API 跨域问题都能定位并解决。

一、先弄清楚：PHP接口为什么会出现跨域

跨域并不是 PHP 主动阻止了请求，而是浏览器执行了同源策略。只要页面所在的源和 API 所在的源不完全一致，就可能进入 CORS 检查。

浏览器判断“源”时主要看三个部分：

协议，例如 http 和 https；
域名，例如 www.example.com 和 api.example.com；
端口，例如 :8080 和 :9000。

例如前端页面运行在：

https://www.example.com

API 地址是：

https://api.example.com/user/profile

虽然两个地址都属于 example.com，但主机名不同，因此仍然是跨源请求。

SVG 配图 1 — 图1：CORS由浏览器执行检查，PHP服务端的任务是正确响应跨域请求和OPTIONS预检。

简单请求和预检请求不是一回事

一些普通的 GET、POST 请求可以直接发出，浏览器收到响应后再检查 CORS 响应头。但当请求使用 JSON、Authorization、自定义请求头，或者 PUT、PATCH、DELETE 等方法时，经常会先发送一个 OPTIONS 请求。

例如前端准备发送：

POST /api/user
Content-Type: application/json
Authorization: Bearer xxxxx

浏览器可能先询问服务器：

OPTIONS /api/user
Origin: https://www.example.com
Access-Control-Request-Method: POST
Access-Control-Request-Headers: authorization, content-type

只有预检响应符合要求，浏览器才继续发送真正的 POST 请求。因此，看到 Network 面板中出现 OPTIONS 并不是异常，它本来就是 CORS 协议的一部分。

二、PHP框架中应该在哪里处理CORS

最合适的位置通常是框架的中间件层。原因很直接：CORS 属于 HTTP 请求进入业务控制器之前的统一规则，不应该散落在每一个 Controller 中。

推荐的处理顺序是：

请求进入 PHP 框架；
CORS 中间件读取 Origin；
判断来源是否在允许列表；
如果是 OPTIONS，则直接返回预检响应；
如果是正常请求，则继续进入认证、路由和控制器；
最终响应统一附加需要的 CORS 响应头。

SVG 配图 2 — 图2：实际配置时应先确定跨域策略，再实现中间件和OPTIONS处理，最后验证响应。

三、先确定你的API到底允许谁访问

配置 CORS 时，不建议看到报错就直接写：

Access-Control-Allow-Origin: *

对于完全公开、无需 Cookie 或其他浏览器凭证的 API，通配符可能是合理的。但后台管理系统、用户中心、订单 API 等接口，更适合使用明确的来源白名单。

例如只允许下面两个前端：

https://www.example.com
https://admin.example.com

还要注意，Origin 必须精确匹配。下面几个地址在 CORS 判断中并不是同一个源：

http://example.com
https://example.com
https://www.example.com
https://www.example.com:8443

开发环境如果使用：

http://localhost:5173

就需要把这个完整 Origin 加入开发环境白名单，而不能只写 localhost。

四、用PHP中间件统一解决CORS

不同 PHP 框架注册中间件的位置不同，但真正需要实现的 CORS 逻辑基本一致。下面给出一个 Laravel 风格的完整中间件例子，重点是展示服务端应该怎样判断 Origin、处理 OPTIONS，并为实际响应附加 CORS 头。

例如建立：

app/Http/Middleware/ApiCors.php

内容如下：

<?php

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;
use Symfony\Component\HttpFoundation\Response;

class ApiCors
{
    private array $allowedOrigins = [
        'https://www.example.com',
        'https://admin.example.com',
        'http://localhost:5173',
    ];

    public function handle(Request $request, Closure $next): Response
    {
        $origin = $request->headers->get('Origin');

        // 没有 Origin 的请求通常来自服务端、命令行或同源请求，
        // 不需要进行浏览器 CORS 判断。
        if ($origin === null) {
            return $next($request);
        }

        // 只允许白名单中的 Origin。
        if (!in_array($origin, $this->allowedOrigins, true)) {
            return response()->json([
                'message' => 'Origin not allowed'
            ], 403);
        }

        // OPTIONS 预检请求不需要进入业务控制器。
        if ($request->isMethod('OPTIONS')) {
            $response = response('', 204);
        } else {
            $response = $next($request);
        }

        $response->headers->set(
            'Access-Control-Allow-Origin',
            $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',
            '600'
        );

        // Origin 是动态返回值时，告诉缓存系统响应会随 Origin 改变。
        $response->headers->set(
            'Vary',
            'Origin'
        );

        return $response;
    }
}

这个中间件做了几件关键的事情：

只允许指定的前端域名访问；
允许常用 REST API 方法；
明确允许 Authorization 和 Content-Type；
OPTIONS 请求直接返回 204，不继续执行控制器；
正常接口返回数据时同样带上 CORS 响应头；
支持需要 Cookie 的凭证请求。

如果你的项目并不需要 Cookie、HTTP 身份凭证等浏览器凭证，可以去掉 Access-Control-Allow-Credentials: true。CORS 配置应和实际业务需求对应，而不是所有项目都使用同一套响应头。

把中间件应用到API路由

如果项目采用路由中间件方式，可以把 API 路由和 OPTIONS 路由放进同一个中间件组。例如在 Laravel 风格的 API 路由文件中：

<?php

use Illuminate\Support\Facades\Route;
use App\Http\Middleware\ApiCors;

Route::middleware(ApiCors::class)->group(function () {

    Route::options('/{path}', function () {
        return response('', 204);
    })->where('path', '.*');

    Route::get('/user/profile', function () {
        return response()->json([
            'id' => 1001,
            'name' => 'demo'
        ]);
    });

    Route::post('/user/profile', function () {
        return response()->json([
            'message' => 'saved'
        ]);
    });
});

如果整个项目的 API 都需要 CORS，更适合把这个中间件放到框架的全局 HTTP 中间件或统一 API 中间件队列中。具体注册文件会随着 PHP 框架和版本变化，但判断 Origin、处理 OPTIONS、添加响应头这几个步骤不会改变。

Laravel、Symfony、ThinkPHP、Slim 等框架如果已经启用了自己的 CORS 中间件或扩展，应优先在现有配置中修改规则，不要再额外写一套重复响应头。

五、Access-Control-Allow-Headers不要漏掉Authorization

很多 API 的 GET 请求可以正常跨域，但一登录或者调用需要 Token 的接口就开始报错，原因往往不是 Token 错了，而是预检请求没有允许 Authorization。

例如前端：

fetch('https://api.example.com/api/user/profile', {
    method: 'GET',
    headers: {
        'Authorization': 'Bearer your-token'
    }
});

服务端至少需要允许：

Access-Control-Allow-Headers: Authorization

如果同时发送 JSON：

Content-Type: application/json

常见配置就是：

Access-Control-Allow-Headers: Content-Type, Authorization, X-Requested-With

不要为了省事允许一堆项目实际上不会使用的请求头。列出前端真正需要发送的 Header，配置更清楚，也更容易排错。

六、OPTIONS预检返回404或405怎么办

这是 PHP 框架跨域中非常常见的问题。浏览器发送：

OPTIONS /api/user/profile

服务器却返回：

404 Not Found

或者：

405 Method Not Allowed

这意味着真正的 POST、PUT 或 DELETE 请求还没有机会发送，问题就已经发生在预检阶段。

解决时检查两层。

1. PHP框架是否接收OPTIONS

OPTIONS 必须能够进入 CORS 中间件。可以建立一个 OPTIONS 通配路由，也可以让全局中间件在路由执行前处理它。

推荐结果是：

HTTP/1.1 204 No Content

204 响应不需要返回业务数据，但必须包含需要的 CORS 响应头。

2. Web服务器有没有提前拦截

如果使用 Nginx、Apache、反向代理、CDN 或 API 网关，需要确认 OPTIONS 没有在到达 PHP 之前被错误拒绝。

判断方法很简单：如果 PHP 中间件日志完全看不到 OPTIONS，而浏览器已经收到 404、403 或 405，就应该继续向 PHP 前面的代理层排查。

七、携带Cookie时为什么不能直接用“*”

如果前端 API 请求需要携带 Cookie，例如：

fetch('https://api.example.com/api/account', {
    credentials: 'include'
});

服务端通常需要返回：

Access-Control-Allow-Origin: https://www.example.com
Access-Control-Allow-Credentials: true

此时不能把允许来源配置成：

Access-Control-Allow-Origin: *

需要携带浏览器凭证时，应返回明确的 Origin。因此实际项目通常维护来源白名单，并根据请求中的 Origin 返回对应的值。

不要简单读取请求中的 Origin，然后未经检查就原样写进 Access-Control-Allow-Origin。这种写法相当于允许任意来源，应先与服务端白名单进行严格匹配。

如果跨域请求依赖 Cookie，而且前后端同时属于不同站点，还需要继续检查 Cookie 的 SameSite、Secure 等属性。这属于 Cookie 策略问题，不能只靠增加 CORS 响应头解决。

八、不要把CORS当作API权限控制

这是一个容易混淆的地方。CORS主要限制浏览器中的 JavaScript 是否能够跨源读取响应，并不是完整的 API 安全机制。

例如攻击者完全可以使用服务器程序、curl 或其他 HTTP 客户端直接调用你的接口：

curl https://api.example.com/api/user/profile

curl 不会像浏览器一样执行 CORS 同源限制。因此 API 仍然需要自己的 Token、Session、签名、权限判断和访问控制。

可以简单理解为：

机制	主要解决的问题
CORS	浏览器是否允许某个前端 Origin 读取跨源响应
登录认证	确认请求者是谁
权限控制	确认当前用户是否有权执行某项操作
CSRF 防护	降低浏览器在用户不知情情况下携带身份执行敏感操作的风险

这几个机制可以同时存在，不能互相替代。

九、如何验证CORS已经配置正确

不要只看前端页面“好像能用了”。更直接的方法是主动模拟一次预检请求，检查服务器到底返回了什么。

例如：

curl -i -X OPTIONS 'https://api.example.com/api/user/profile' \
  -H 'Origin: https://www.example.com' \
  -H 'Access-Control-Request-Method: POST' \
  -H 'Access-Control-Request-Headers: Authorization, Content-Type'

示例响应：

HTTP/1.1 204 No Content
Access-Control-Allow-Origin: https://www.example.com
Access-Control-Allow-Methods: GET, POST, PUT, PATCH, DELETE, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization, X-Requested-With
Access-Control-Allow-Credentials: true
Access-Control-Max-Age: 600
Vary: Origin

如果这里已经正确，再测试真正的接口：

curl -i 'https://api.example.com/api/user/profile' \
  -H 'Origin: https://www.example.com' \
  -H 'Authorization: Bearer your-token'

实际 GET、POST 等响应也必须包含相应的 Access-Control-Allow-Origin，不能只有 OPTIONS 有。

需要注意，curl 可以帮助检查 HTTP 响应，但它本身不会执行浏览器的 CORS 安全策略。因此最终还应该回到 Chrome、Edge 或 Firefox 的开发者工具中确认。

十、跨域报错时应该按什么顺序排查

面对 CORS 报错，不建议一上来修改大量响应头。先观察浏览器 Network 面板，判断错误发生在 OPTIONS 还是正式请求，再针对具体环节处理。

SVG 配图 3 — 图3：跨域排查应先看OPTIONS是否成功，再检查Origin、Method、Headers和正式接口。

常见错误1：没有Access-Control-Allow-Origin

浏览器经常提示类似：

No 'Access-Control-Allow-Origin' header is present...

重点检查实际响应中是否存在：

Access-Control-Allow-Origin: https://www.example.com

不要只看 PHP 源代码“已经 set 了”，应直接在 Network 面板或 curl 响应中确认最终 HTTP Header。

常见错误2：OPTIONS返回正常，但POST仍然失败

这通常说明预检通过了，但真正的 POST 响应没有带 CORS Header。中间件必须同时处理 OPTIONS 和正常业务响应。

常见错误3：Authorization没有被允许

如果错误信息包含：

Request header field authorization is not allowed...

检查：

Access-Control-Allow-Headers

中是否明确包含 Authorization。

常见错误4：域名看起来一样却仍然失败

检查完整 Origin，而不是只看主域名。例如：

https://www.example.com
https://example.com

这两个就是不同的 Origin。协议或端口不同也一样。

常见错误5：响应出现两个Allow-Origin

有些项目在 Nginx 设置了一次 CORS，又在 PHP 框架中设置一次，最终可能得到重复响应头。

例如出现类似：

Access-Control-Allow-Origin: *
Access-Control-Allow-Origin: https://www.example.com

浏览器可能拒绝这种响应。比较稳妥的做法是明确由一个层负责 CORS：如果已经由 PHP 框架统一管理，就不要再让 Nginx 添加第二套相同响应头。

常见错误6：开发环境能用，生产环境突然失败

重点比较生产环境实际的 Origin、HTTPS、反向代理和 CDN 缓存。

例如开发环境允许：

http://localhost:5173

上线后前端变成：

https://www.example.com

如果生产域名没有进入白名单，自然会失败。

如果根据不同 Origin 动态返回 Access-Control-Allow-Origin，还应考虑：

Vary: Origin

这样可以告诉 CDN、代理缓存等系统：不同 Origin 得到的响应头可能不同，避免把一个来源的 CORS 响应错误复用给另一个来源。

十一、PHP框架配置CORS时的完整检查表

SVG 配图 4 — 图4：PHP框架解决CORS问题时，可以按这六项逐一检查，避免遗漏关键配置。

实际项目中，可以按下面的顺序完成配置：

列出允许访问 API 的完整 Origin，不只记录域名，还要考虑协议和端口。
明确 API 使用的 GET、POST、PUT、PATCH、DELETE 等方法。
检查前端是否发送 Authorization、Content-Type 或其他自定义 Header。
确保 OPTIONS 能进入 CORS 中间件，并正常返回 204 或其他成功状态。
让 OPTIONS 和真正的业务响应都返回正确的 CORS Header。
需要 Cookie 时使用明确 Origin，并配置 Access-Control-Allow-Credentials。
动态返回 Origin 时考虑加入 Vary: Origin。
避免 Nginx、CDN 和 PHP 框架同时重复添加同一个 CORS Header。
使用 curl 检查 HTTP 层，再用浏览器开发者工具进行最终验证。

十二、总结

PHP框架解决 API 跨域问题的核心，并不是简单增加一条 Access-Control-Allow-Origin: *，而是建立一套完整的 CORS 处理流程。

对于普通项目，比较稳妥的方案是把 CORS 放进统一中间件：使用白名单检查 Origin，明确允许的方法和请求头，正确响应 OPTIONS 预检，并确保正式业务响应同样携带 CORS Header。需要 Cookie 时，再增加凭证配置并使用明确的 Origin。

如果配置后仍然报错，就从浏览器 Network 面板开始排查：先看有没有 OPTIONS，再看 OPTIONS 的状态码，然后逐项核对 Access-Control-Allow-Origin、Access-Control-Allow-Methods 和 Access-Control-Allow-Headers。这样通常可以很快判断问题究竟出在 PHP 框架、路由、Web 服务器，还是前端请求参数。

同时要记住，CORS解决的是浏览器跨源访问问题，并不能替代 API 的登录认证和权限控制。把跨域策略和业务安全分开处理，后续维护会清晰得多。