Hyperf中CORS中间件失效主因是OPTIONS预检请求被路由层拦截未进入中间件，需全局注册中间件、显式声明或启用auto_options路由补全、校验Origin白名单，并确保执行顺序在鉴权之前。
Hyperf里CORS中间件加了Access-Control-Allow-Origin等头却没生效，大概率不是头没写对，而是中间件根本没跑进去——特别是OPTIONS预检请求被路由层提前拦截了，压根没走到你的CorsMiddleware。
为什么OPTIONS请求返回405而不是204
Hyperf默认路由组件遇到未知OPTIONS路径时，会抛出HttpException并返回405 Method Not Allowed，此时中间件链早已中断，你写的process方法根本不会执行。
- 检查日志是否出现
MethodNotAllowedHttpException或405响应 - 确认该
OPTIONS路径在路由定义中是否存在（哪怕只是空路由） - Hyperf 3.x 默认不自动注册
OPTIONS路由，必须显式声明或启用路由自动补全
中间件注册位置必须是全局级，不能只挂路由组
CorsMiddleware如果只在某个@Middleware注解或middleware数组里配给某几个路由，那其他路径（尤其是预检请求打到未配置的路径上）依然会掉进405陷阱。
- 正确做法：把中间件加到
config/autoload/middlewares.php的'http'数组顶层，确保所有HTTP请求都经过它 - 错误写法：
Router::addRoute(['GET', 'OPTIONS'], '/api/user', [...])这种手动补OPTIONS易遗漏，且不覆盖根路径等边缘情况 - 若用Hyperf 3.1+，可配合
hyperf/routing的auto_options配置自动注入OPTIONS路由，但需确认已启用
Response对象必须从Context取，不能new Response()
很多示例直接new \Hyperf\HttpMessage\Server\Response()构造响应，这会导致后续中间件或控制器无法复用该对象，Header丢失、Body为空、状态码错乱。
- 必须用
Context::get(ResponseInterface::class)获取当前上下文响应实例 - 所有
withHeader()操作要链式调用后，再用Context::set()写回上下文 -
OPTIONS分支里返回前，务必调用withStatus(204)且withBody(new SwooleStream(''))，否则Swoole可能卡住连接
生产环境别用*配Access-Control-Allow-Origin加credentials
浏览器明确禁止Access-Control-Allow-Origin: *和Access-Control-Allow-Credentials: true同时存在。开发时图省事这么写，上线就会发现带cookie的请求始终被拦。
- 必须做Origin白名单校验：
if (in_array($origin, $this->allowedOrigins)) { ... } - 响应头里
Access-Control-Allow-Origin值得设成具体域名（如https://your-app.com），不能是* -
Access-Control-Allow-Methods和Access-Control-Allow-Headers也建议列明，避免*引发兼容性问题（尤其老版Safari）
最常被忽略的是中间件执行顺序——CORS必须放在鉴权中间件之前，否则预检请求因缺少token被Auth中间件拒绝，连头都加不上。这个顺序一旦错，排查时容易反复怀疑头设置逻辑，其实问题早在线路入口就断了。
