PHP项目怎么解决跨域预检失败？

wen PHP项目 2026-06-07 35

PHP项目跨域预检失败全解析：从原理到实战解决方案

目录导读

什么是跨域预检请求？为什么它会失败？
PHP跨域预检失败的六大常见原因
终极解决方案：PHP后端配置全攻略
实战代码：完整跨域中间件示例
QA问答：开发者最常踩的坑
浏览器调试技巧与工具推荐

什么是跨域预检请求？为什么它会失败？

Q：为什么我的前端请求在控制台显示“CORS预检失败”？
A：当浏览器检测到请求属于“非简单请求”（如POST的JSON数据、带自定义头等），会先发送一个OPTIONS预检请求到服务器，验证服务器是否允许该跨域行为,预检失败意味着OPTIONS请求未被服务器正确响应。

PHP项目怎么解决跨域预检失败？

核心机制：

简单请求（GET/HEAD/POST + 标准Content-Type）不会触发预检。
非简单请求（PUT/DELETE/PATCH + application/json等）会先发OPTIONS。
预检成功需满足：服务器正确返回 Access-Control-Allow-Origin、Allow-Methods、Allow-Headers 等头。

PHP跨域预检失败的六大常见原因

服务器未处理OPTIONS请求
PHP框架未对OPTIONS请求返回200状态码,导致浏览器误判。
Access-Control-Allow-Origin缺失或配置错误
只有与当前请求来源完全匹配才能通过（注意：不支持携带凭据）。
Access-Control-Allow-Headers未包含自定义头
如果前端发送Authorization或X-Requested-With,必须显式声明。
Access-Control-Allow-Methods未包含实际请求方法
例如前端用DELETE,但服务器只允许GET和POST。
Access-Control-Allow-Credentials设置冲突
使用withCredentials: true时，Origin不能为,必须指定具体域名。
PHP输出前已发送响应头
在PHP输出HTML或JSON后再设置Header无效。

终极解决方案：PHP后端配置全攻略

全局中间件（推荐用于框架如Laravel/ThinkPHP）

// Laravel中，在App\Http\Middleware\CorsMiddleware.php
public function handle($request, Closure $next)
{
    // 如果是预检请求，直接返回204
    if ($request->isMethod('OPTIONS')) {
        return response('', 204)
            ->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');
    }
    $response = $next($request);
    // 添加跨域头到实际响应
    $response->header('Access-Control-Allow-Origin', '*');
    $response->header('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS');
    $response->header('Access-Control-Allow-Headers', 'Content-Type, Authorization, X-Requested-With');
    return $response;
}

原生PHP通用配置

<?php
// 放在入口文件 index.php 最顶部
// 允许所有域名（生产环境建议指定具体域名）
header('Access-Control-Allow-Origin: https://your-frontend-domain.com');
// 或者使用动态来源（需验证合法性）
// $origin = $_SERVER['HTTP_ORIGIN'] ?? '';
// if (in_array($origin, ['https://allowed.com'])) {
//     header("Access-Control-Allow-Origin: $origin");
// }
header('Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS');
header('Access-Control-Allow-Headers: Content-Type, Authorization, X-Requested-With');
header('Access-Control-Allow-Credentials: true'); // 如需携带Cookie
header('Access-Control-Max-Age: 86400'); // 预检结果缓存1天
// 处理预检请求
if ($_SERVER['REQUEST_METHOD'] === 'OPTIONS') {
    http_response_code(204); // 或200
    exit();
}

Apache/Nginx层配置（更高性能）

Apache (.htaccess)

Header set Access-Control-Allow-Origin "*"
Header set Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS"
Header set Access-Control-Allow-Headers "Content-Type, Authorization"
RewriteEngine On
RewriteCond %{REQUEST_METHOD} OPTIONS
RewriteRule ^(.*)$ $1 [R=204,L]

Nginx配置片段

location / {
    add_header Access-Control-Allow-Origin "*";
    add_header Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS";
    add_header Access-Control-Allow-Headers "Content-Type, Authorization";
    if ($request_method = 'OPTIONS') {
        add_header Content-Length 0;
        add_header Content-Type text/plain;
        return 204;
    }
}

实战代码：完整跨域中间件示例

以下是一个可直接复用的PHP中间件类（适用于基于Composer的项目）：

class CorsMiddleware
{
    private $allowedOrigins = [
        'https://admin.example.com',
        'https://app.example.com'
    ];
    public function handle()
    {
        $origin = $_SERVER['HTTP_ORIGIN'] ?? '';
        if (in_array($origin, $this->allowedOrigins)) {
            header("Access-Control-Allow-Origin: $origin");
        } else {
            // 不支持来源时，可拒绝或返回默认
            header('Access-Control-Allow-Origin: https://default.com');
        }
        header('Access-Control-Allow-Credentials: true');
        header('Access-Control-Max-Age: 3600');
        header('Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS');
        header('Access-Control-Allow-Headers: Content-Type, Authorization, X-Requested-With, X-CSRF-TOKEN');
        if ($_SERVER['REQUEST_METHOD'] === 'OPTIONS') {
            http_response_code(204);
            exit;
        }
    }
}
// 在入口调用
(new CorsMiddleware())->handle();

QA问答：开发者最常踩的坑

Q1：为什么我设置了 Header，预检还是失败？
A：检查是否在 PHP 输出语句（如 echo, print_r）之后设置 Header，应放在所有输出之前，确认 PHP 文件无BOM头。

Q2：为什么本地开发跨域正常，线上就失败？
A：线上环境可能经过 Nginx/Apache 反向代理，需在代理层也配置跨域头，或在 PHP 端统一处理，检查线上域名是否在 allowedOrigins 列表中。

Q3：预检请求总是成功，但正式请求报错？
A：预检成功后，实际请求也需要返回相同的跨域头，常见错误是只对OPTIONS请求返回头，而对GET/POST请求忘记添加。

*Q4：使用 `Access-Control-Allow-Origin: 时能携带 Cookie 吗？** A：不能！*不支持withCredentials: true，必须指定具体域名并设置Access-Control-Allow-Credentials: true`。

Q5：预检请求的响应状态码是 200 还是 204？
A：两者均可，但推荐 204 No Content（节省带宽）,同时避免某些框架自动添加额外内容。

浏览器调试技巧与工具推荐

Chrome DevTools Network 面板
- 过滤“XHR”或“Fetch”类型
- 查看请求的 Request Headers 中是否包含 Origin
- 检查响应头中的 Access-Control-* 字段

使用 CURL 模拟预检请求

curl -X OPTIONS https://api.yoursite.com/path \
  -H "Origin: https://your-frontend.com" \
  -H "Access-Control-Request-Method: POST" \
  -H "Access-Control-Request-Headers: Content-Type, Authorization"

查看返回的 Access-Control-Allow-Origin 是否正确。