Nginx中Access-Control-Max-Age设置预检请求缓存时间教程-Nginx-PHP中文网

Access-Control-Max-Age用于缓存CORS预检响应，减少OPTIONS请求；单位为秒，推荐值≤86400；需在Nginx location块中用add_header设置，并注意Credentials与Origin配合。

nginx中access-control-max-age设置预检请求缓存时间教程

在 Nginx 中设置 Access-Control-Max-Age，是为了让浏览器缓存 CORS 预检请求（OPTIONS）的响应结果，避免重复发起 OPTIONS 请求，提升接口性能。这个值不是必须设置的，但合理配置能减少不必要的网络开销。

理解 Access-Control-Max-Age 的作用

当浏览器发起跨域请求且满足“非简单请求”条件（如带自定义 header、使用 PUT/DELETE 方法、Content-Type 为 application/json 等），会先发一个 OPTIONS 预检请求。如果响应中包含 Access-Control-Max-Age，浏览器就会缓存该预检响应一段时间，在此期间相同 URL 和请求头组合的后续请求不再发送 OPTIONS。

注意：该字段只影响预检响应的缓存时间，不影响实际请求（GET/POST 等）的缓存行为；它的单位是秒，最大推荐值一般不超过 86400（24 小时）。

Nginx 中添加 Access-Control-Max-Age 的方法

在对应 server 或 location 块中，通过 add_header 指令添加响应头即可。需确保该 header 在预检请求（OPTIONS）和实际请求中都生效（除非你明确只对某类请求设值）：

在 location 块中统一添加（推荐）：

location /api/ {
    add_header 'Access-Control-Allow-Origin' '*';
    add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS, PUT, DELETE';
    add_header 'Access-Control-Allow-Headers' 'DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range,Authorization';
    add_header 'Access-Control-Expose-Headers' 'Content-Length,Content-Range';
    add_header 'Access-Control-Max-Age' 86400;
    
    if ($request_method = 'OPTIONS') {
        add_header 'Access-Control-Allow-Origin' '*';
        add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS, PUT, DELETE';
        add_header 'Access-Control-Allow-Headers' 'DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range,Authorization';
        add_header 'Access-Control-Max-Age' 86400;
        add_header 'Access-Control-Allow-Credentials' 'true';
        add_header 'Access-Control-Allow-Origin' '$http_origin';
        add_header 'Vary' 'Origin';
        add_header 'Access-Control-Allow-Credentials' 'true';
        return 204;
    }
}

关键点说明：
- add_header 指令默认不会继承父级块，所以建议在处理跨域的 location 内显式写出所有相关 header；
- 若启用了 Access-Control-Allow-Credentials: true，则 Access-Control-Allow-Origin 不能为 *，需动态设为 $http_origin 并配合 Vary: Origin；
- Access-Control-Max-Age 可以和其它 CORS 头一起写在 OPTIONS 响应里，也可在主逻辑中统一加（只要最终响应含该头即可）；
- Nginx 默认不缓存 OPTIONS 响应，但加了 Access-Control-Max-Age 后，浏览器端会按此值缓存预检结果。

验证是否生效

部署后可通过浏览器开发者工具的 Network 面板检查 OPTIONS 请求的响应头：

发起一次跨域请求（如带 Authorization header 的 POST），观察是否出现 OPTIONS 请求；
查看其响应头中是否有 Access-Control-Max-Age: 86400；
短时间内重复触发相同请求，确认后续不再发出新的 OPTIONS（只有第一次有，之后直接发主请求）；

也可用 curl 模拟：

curl -X OPTIONS -H "Origin: https://example.com" -I http://your-nginx-domain/api/test

查看返回头是否包含该字段。

常见问题与注意事项

设置后未生效？可能原因包括：

Nginx 配置未重载：执行 nginx -t && nginx -s reload；
CDN 或反向代理（如 Cloudflare、SLB）覆盖或删除了自定义 header，需检查中间层配置；
应用后端（如 Node.js、Python）也设置了 CORS，导致 Nginx 的 header 被覆盖（Nginx 的 add_header 默认不覆盖已存在的同名 header，可用 always 参数强制添加：add_header 'Access-Control-Max-Age' 86400 always;）；
浏览器缓存了旧的预检响应（比如之前 Max-Age 是 0 或未设置），可清空浏览器缓存或换隐身窗口测试。