OPTIONS 请求返回 404 错误如何解决？

Question

在前后端分离项目中，浏览器发起跨域请求时会先发送 OPTIONS 预检请求。若服务器未正确处理该请求，将返回 404 错误，导致实际请求无法执行。常见于 Nginx、Spring Boot 或 Node.js 服务未配置预检请求支持。解决方法包括：确保后端路由或中间件允许 OPTIONS 方法；添加 CORS 相关响应头（如 Access-Control-Allow-Origin、Access-Control-Allow-Methods）；在 Nginx 中显式拦截 OPTIONS 请求并返回 200 状态。忽略预检处理将直接导致接口调用失败。

Answer 1

前后端分离架构下的跨域预检请求（OPTIONS）深度解析

1. 什么是跨域与CORS机制

在现代前后端分离项目中，前端通常部署在独立域名或端口上（如 http://localhost:3000），而后端API服务运行于另一地址（如 http://api.example.com:8080）。当浏览器检测到请求的源（Origin）与当前页面不一致时，会触发同源策略限制。

为安全起见，浏览器引入了跨域资源共享（Cross-Origin Resource Sharing, CORS）机制。对于某些“非简单请求”（例如使用了自定义Header、PUT/DELETE方法、JSON格式Body等），浏览器会在正式请求前自动发送一个 OPTIONS 预检请求，以确认服务器是否允许该跨域操作。

2. OPTIONS预检请求的触发条件

• 请求方法为非GET、POST、HEAD之一（如PUT、DELETE、PATCH）
• 设置了自定义请求头（如 X-Token、Authorization-Bearer）
• Content-Type 为 application/json、application/xml 等非表单类型
• 携带了 Access-Control-Request-Headers 或 Access-Control-Request-Method 头信息

一旦满足上述任一条件，浏览器将先发起 OPTIONS 请求，目标URL相同，但不含实际数据体，仅用于探测权限。

3. 常见错误现象：OPTIONS 返回 404

若后端服务未显式处理 OPTIONS 方法，常见的表现如下：

现象	可能原因	影响范围
OPTIONS 请求返回 404 Not Found	Nginx 未配置 location 拦截 OPTIONS；Spring Boot Controller 缺少 @RequestMapping(method = RequestMethod.OPTIONS)	所有复杂跨域请求失败
OPTIONS 返回 200，但缺少 CORS 头	中间件未添加 Access-Control-Allow-* 响应头	浏览器拒绝执行主请求
Preflight 超时或被防火墙拦截	网络策略或代理层未透传 OPTIONS 方法	开发环境正常，生产环境异常

4. 解决方案层级分析

根据系统架构不同，可在多个层次解决 OPTIONS 预检问题：

4.1 Nginx 层面拦截并响应 OPTIONS

推荐在反向代理层统一处理，避免业务代码冗余。示例配置如下：

location /api/ {
    if ($request_method = OPTIONS) {
        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, X-Requested-With";
        add_header Access-Control-Max-Age 1728000;
        add_header Content-Length 0;
        add_header Content-Type text/plain;
        return 204;
    }

    proxy_pass http://backend_service;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
}
    

4.2 Spring Boot 中通过全局配置支持 CORS

使用 Java Config 方式注册 CorsConfigurationSource：

@Configuration
@EnableWebMvc
public class CorsConfig implements WebMvcConfigurer {

    @Override
    public void addCorsMappings(CorsRegistry registry) {
        registry.addMapping("/api/**")
                .allowedOriginPatterns("*")
                .allowedMethods("GET", "POST", "PUT", "DELETE", "OPTIONS")
                .allowedHeaders("*")
                .allowCredentials(true)
                .maxAge(3600);
    }
}
    

4.3 Node.js Express 框架中的中间件处理

利用 cors 中间件或手动设置响应头：

const express = require('express');
const app = express();

app.use((req, res, next) => {
    res.header('Access-Control-Allow-Origin', '*');
    res.header('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS');
    res.header('Access-Control-Allow-Headers', 'Content-Type, Authorization');

    if (req.method === 'OPTIONS') {
        res.sendStatus(200);
    } else {
        next();
    }
});
    

5. 架构级流程图：预检请求处理路径

graph TD
            A[前端发起跨域请求] --> B{是否为简单请求?}
            B -- 是 --> C[直接发送主请求]
            B -- 否 --> D[浏览器自动发送 OPTIONS 预检]
            D --> E[Nginx 是否匹配 OPTIONS?]
            E -- 是 --> F[Nginx 返回 204 + CORS Headers]
            E -- 否 --> G[转发至后端应用]
            G --> H[Spring Boot/Node.js 是否支持 OPTIONS?]
            H -- 是 --> I[返回 200 并携带 CORS 头]
            H -- 否 --> J[返回 404/405 错误]
            I --> K[浏览器发送真实请求]
            F --> K
            K --> L[获取最终响应结果]

6. 生产环境最佳实践建议

1. 优先在 Nginx 层统一处理 OPTIONS 请求，减少后端压力
2. CORS 白名单应避免使用 *，尤其在涉及 Credential 时
3. 合理设置 Access-Control-Max-Age，缓存预检结果（建议 1 小时）
4. 日志监控中需单独追踪 OPTIONS 请求状态码分布
5. 微服务网关（如 Kong、Spring Cloud Gateway）也应配置全局 CORS 策略
6. 测试阶段使用 curl 模拟 OPTIONS 请求验证响应头完整性
7. 避免在多个层级重复设置 CORS 头导致冲突
8. 考虑使用 Preflight Proxy 模式集中管理跨域策略
9. 定期审计 API 网关与负载均衡器对非主流 HTTP 方法的支持情况
10. 文档化所有对外暴露接口的跨域策略，便于前端协作