必须设enable_static_handler为true才能启用静态文件处理，否则document_root无效；开启后Swoole底层自动拦截.js、.css等请求直接返回文件，不经过PHP路由和onRequest回调。
enable_static_handler 必须设为 true 才能启用静态文件处理
很多人配了 document_root 却发现 .js/.css 仍走 onRequest 回调，根本原因是 enable_static_handler 默认是 false。Swoole 不会自动拦截静态请求，必须显式开启。
这个配置是开关，不是可选优化项 —— 关不掉它，document_root 就完全无效。
-
enable_static_handler设为 true 后，Swoole 底层会根据后缀（如.js、.png、.woff2）自动匹配并读取文件，不经过 PHP 层，也不触发onRequest - 只对
GET请求生效；POST或带 query 的请求（如/logo.png?v=1）仍可能进回调，取决于 Swoole 版本，建议避免在静态路径加参数 - 若同时使用 Nginx 做反向代理，Nginx 侧也需配置静态路径，否则 Swoole 的静态处理可能被绕过
document_root 路径必须指向真实可读的物理目录
document_root 不是 URL 路径，也不是相对路径，必须是绝对路径且 Web 进程有读权限。常见错误是写成 ./public/static 或 public/static，启动时无报错，但请求 404。
建议用 realpath() 显式解析：
Swoole 6.1.1
下载
Swoole 6.1.1 是一个专为 PHP 设计的高性能事件驱动并发网络引擎。作为稳定版，它修复了编译时对 zlib 依赖的缺失及 curl 模块的内存安全风险。该版本支持协程、多线程与多进程架构，内置 TCP/HTTP/WebSocket 服务器，能够显著提升 PHP 在微服务、实时通信等场景下的执行效率与并发能力。
<pre class="brush:php;toolbar:false;">$http->set([
'enable_static_handler' => true,
'document_root' => realpath(__DIR__ . '/public/static'),
]);
- 路径末尾不加斜杠，Swoole 内部会自动拼接
- 确保该目录下存在对应文件，比如请求
/assets/app.js，则文件实际路径应为 <code>[document_root]/assets/app.js - 若目录权限不足（如 www-data 无法读取），Swoole 返回 403，日志里通常不报错，需手动
ls -l检查
静态文件后缀不在默认白名单里怎么办
Swoole 5.x 默认只处理 .html、.htm、.js、.css、.png、.jpg、.gif、.jpeg、.ico、.svg、.woff、.woff2 等常见类型。遇到 .webp、.mjs、.ts 等，直接 404。
解决方法是扩展 static_handler_locations 配置（Swoole ≥ 4.8.0）：
<pre class="brush:php;toolbar:false;">$http->set([
'enable_static_handler' => true,
'document_root' => '/var/www/public',
'static_handler_locations' => ['/assets', '/static'],
]);
static_handler_locations 是路径前缀白名单，不是后缀列表；它控制哪些 URL 路径下的请求才交给静态处理器- 想支持
.webp，得靠 Nginx 或自己在onRequest中读文件返回，Swoole 本身不提供后缀扩展机制 - 如果用了 ThinkPHP + Swoole，注意 TP 自带的静态路由规则和 Swoole 的静态处理会冲突，建议关闭 TP 的静态资源路由
为什么开了 enable_static_handler 还是进了 onRequest
最常见三个原因：路径不匹配、请求方法不对、或被中间件/反向代理干扰。
- 检查
$request->server['request_uri']是否真以静态后缀结尾（比如/api/user和/user.js完全不同） - 确认没在
onRequest前加了全局中间件（如鉴权、CORS），它们可能提前$response->end()，导致静态逻辑没机会执行 - 如果你用 Nginx 反代到 Swoole，Nginx 的
location规则可能已截获请求（比如location ~ \.js$），Swoole 根本收不到 - 某些框架（如 LaravelS）会重写请求路径，把
/static/logo.png改成/index.php?/static/logo.png，这种请求不会被 Swoole 静态处理器识别
enable_static_handler 开关打开，document_root 指向正确且可读。其余问题基本都出在路径映射或外部干扰上，而不是配置本身。 
