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 不会自动通配或推断，必须手动写全：
- 在
location块中使用add_header指令，值为英文逗号分隔的头名称列表 - 不带空格更稳妥（部分浏览器对空格敏感），例如：
"X-Request-ID,X-User-ID,Authorization" - 头名大小写需与前端代码完全一致，推荐统一用首字母大写的驼峰格式（如
X-Api-Key，而非x-api-key） - 标准头如
Content-Type、Authorization也要一并写入，不能省略
这个配置必须出现在 OPTIONS 预检响应里
浏览器只在 OPTIONS 预检响应中检查 Access-Control-Allow-Headers。如果 Nginx 没有为 OPTIONS 请求返回该头，主请求会被直接拦截：
前端设计优化skill
下载
前端设计与 UI/UX 全方位优化专家。覆盖视觉层次、排版系统、色彩理论、响应式布局、交互体验、动画动效、无障碍访问、性能优化八大维度，帮助开发者将普通页面升级为高品质产品级界面。前端设计与 UI/UX 全方位优化专家。覆盖视觉层次、排版系统、色彩理论、响应式布局、交互体验、动画动效、无障碍访问、性能优化八大维度，帮助开发者将普通页面升级为高品质产品级界面。
- 用
if ($request_method = 'OPTIONS')拦截预检请求 - 在 if 块内重复设置
Access-Control-Allow-Headers，确保它和主请求响应保持一致 - 配合
return 204终止处理，避免被后续 proxy_pass 或 rewrite 干扰 - 不要依赖 try_files 或 rewrite 处理 OPTIONS，它们无法保证 headers 正确输出
注意生产环境禁用通配符 *
Access-Control-Allow-Headers: * 在大多数现代浏览器中已被禁止用于含凭据的请求，且 Nginx 本身也不支持该写法用于非简单头：
立即学习“前端免费学习笔记（深入）”；
- 通配符
*只在Access-Control-Allow-Origin中对无凭据请求有效，不适用于Allow-Headers - 必须写死头名列表，哪怕只有 1 个自定义头也要单独列出
- 若前端动态加头（如不同环境加不同 trace 头），需提前约定并同步更新 Nginx 配置
验证是否生效的小技巧
可直接用 curl 模拟预检请求，检查响应头是否完整：
curl -I -X OPTIONS -H "Origin: https://example.com" -H "Access-Control-Request-Headers: X-Request-ID,X-User-ID" http://your-api/- 确认返回中包含
Access-Control-Allow-Headers: X-Request-ID,X-User-ID,... - 同时检查
Access-Control-Allow-Origin是否匹配 Origin，且未使用*（若启用了 credentials）
