Nginx需在反向代理层统一配置CORS头以支持Hyperf跨域：指定Access-Control-Allow-Origin为具体域名（禁用*）、包含OPTIONS方法、匹配前端请求头、启用credentials时严格限制源，并对OPTIONS预检直接返回204。
Hyperf 默认不处理跨域请求，单机部署时需在 Nginx 层统一添加 CORS 响应头，避免后端重复配置或暴露敏感头信息。
确认跨域请求来源与目标路径
先明确前端访问地址（如 https://admin.example.com）和 Hyperf 后端服务监听地址（如 127.0.0.1:9501）。Nginx 作为反向代理，需将前端请求转发至 Hyperf，并在响应中注入合法的跨域头。若前端未固定域名（如开发环境用 localhost:3000、测试环境用 test-admin.example.com），建议按需设置 Access-Control-Allow-Origin，生产环境切勿设为 *（尤其当携带凭据时）。
Nginx 配置核心 CORS 头项
在 server 块或 location 块中加入以下响应头：
- add_header Access-Control-Allow-Origin "https://admin.example.com"; —— 显式指定可信源，支持单个域名；多源需通过变量或 if 判断动态设置
- add_header Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS"; —— 列出允许的 HTTP 方法，OPTIONS 必须包含以支持预检
- add_header Access-Control-Allow-Headers "Content-Type, Authorization, X-Requested-With"; —— 匹配前端实际发送的自定义头，Hyperf 常见需透传 Authorization（JWT）、X-Requested-With（防 CSRF）
- add_header Access-Control-Allow-Credentials "true"; —— 若前端设置了 withCredentials: true，此项必须为 true，且 Access-Control-Allow-Origin 不能为 *
- add_header Access-Control-Expose-Headers "X-Total-Count, X-Pagination"; —— 若 Hyperf 接口返回分页等自定义响应头，需在此显式声明才可被前端 JS 读取
正确处理预检请求（OPTIONS）
浏览器对非简单请求会先发 OPTIONS 请求。Nginx 应直接返回 204，不转发给 Hyperf，减少后端压力：
- 在 location ~ ^/api/.* { } 块内添加：if ($request_method = 'OPTIONS') { add_header Access-Control-Allow-Origin "https://admin.example.com"; 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-Allow-Credentials "true"; return 204; }
- 注意：if 在 location 中可用，但不宜嵌套复杂逻辑；更稳妥做法是用 map 指令提前定义跨域策略变量，再配合 add_header 使用
验证与调试要点
配置生效后，用 curl 或浏览器开发者工具检查响应头是否完整输出：
- 发起一个带 Origin 和 Authorization 的 POST 请求，确认响应含全部 CORS 头且值符合预期
- 触发预检（如带 Content-Type: application/json 的 PUT 请求），观察 OPTIONS 是否返回 204 且含对应头
- 若仍报错，检查 Nginx error.log 是否有 rewrite 或 proxy_pass 相关警告；确认 proxy_set_header Host $host; 和 proxy_set_header X-Real-IP $remote_addr; 已配置，避免 Hyperf 日志 IP 或 host 异常
