Nginx CORS 策略中如何配置 Access-Control-Allow-Headers 允许前端发送自定义请求头

Nginx必须在OPTIONS预检响应中显式、精准列出所有自定义请求头（如X-User-ID、X-Request-ID），大小写和拼写须与前端完全一致，且需配合add_header指令和return 204确保生效。

要让前端成功发送带自定义请求头（比如 X-User-ID、X-Request-ID、X-App-Version）的跨域请求，Nginx 必须在预检响应中明确列出这些头名——光写 Access-Control-Allow-Headers 是不够的，必须精准匹配前端实际发的头名，且大小写、拼写、空格都要一致。

必须显式列出所有自定义请求头名

浏览器会严格校验 Access-Control-Allow-Headers 响应头中的值是否包含前端请求携带的每一个自定义头。Nginx 不会自动通配或推断，必须手动写全：

1. 在 location 块中使用 add_header 指令，值为英文逗号分隔的头名称列表
2. 不带空格更稳妥（部分浏览器对空格敏感），例如："X-Request-ID,X-User-ID,Authorization"
3. 头名大小写需与前端代码完全一致，推荐统一用首字母大写的驼峰格式（如 X-Api-Key，而非 x-api-key）
4. 标准头如 Content-Type、Authorization 也要一并写入，不能省略

这个配置必须出现在 OPTIONS 预检响应里

浏览器只在 OPTIONS 预检响应中检查 Access-Control-Allow-Headers。如果 Nginx 没有为 OPTIONS 请求返回该头，主请求会被直接拦截：

1. 用 if ($request_method = 'OPTIONS') 拦截预检请求
2. 在 if 块内重复设置 Access-Control-Allow-Headers，确保它和主请求响应保持一致
3. 配合 return 204 终止处理，避免被后续 proxy_pass 或 rewrite 干扰
4. 不要依赖 try_files 或 rewrite 处理 OPTIONS，它们无法保证 headers 正确输出

注意生产环境禁用通配符 *

Access-Control-Allow-Headers: * 在大多数现代浏览器中已被禁止用于含凭据的请求，且 Nginx 本身也不支持该写法用于非简单头：

1. 通配符 * 只在 Access-Control-Allow-Origin 中对无凭据请求有效，不适用于 Allow-Headers
2. 必须写死头名列表，哪怕只有 1 个自定义头也要单独列出
3. 若前端动态加头（如不同环境加不同 trace 头），需提前约定并同步更新 Nginx 配置

验证是否生效的小技巧

可直接用 curl 模拟预检请求，检查响应头是否完整：

1. curl -I -X OPTIONS -H "Origin: https://example.com" -H "Access-Control-Request-Headers: X-Request-ID,X-User-ID" http://your-api/
2. 确认返回中包含 Access-Control-Allow-Headers: X-Request-ID,X-User-ID,...
3. 同时检查 Access-Control-Allow-Origin 是否匹配 Origin，且未使用 *（若启用了 credentials）