Swoole HTTP服务怎么开启静态文件处理-Swoole-PHP中文网

必须设enable_static_handler为true才能启用静态文件处理，否则document_root无效；开启后swoole底层自动拦截.js、.css等请求直接返回文件，不经过php路由和onrequest回调。

swoole http服务怎么开启静态文件处理

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 指向正确且可读。其余问题基本都出在路径映射或外部干扰上，而不是配置本身。