Swoole静态文件处理器配置方法-Swoole-PHP中文网

别直接开 enable_static_handler 上生产——它只做基础文件存在判断，无缓存头、无压缩、不支持断点续传，且挤占worker协程资源；常见404或仍进onrequest，主因是document_root未用绝对路径、static_handler_locations白名单限制或回调中提前end()覆盖。

swoole静态文件处理器配置方法

别直接开 enable_static_handler 上生产 —— 它只做最基础的文件存在性判断，不加缓存头、不压缩、不支持断点续传，还挤占 worker 协程资源。

为什么 `enable_static_handler` 开了却没生效

常见现象是请求返回 404，或始终走到 on('request') 回调里。根本原因通常是路径映射没对上：

document_root 必须是绝对路径，相对路径（如 ./public）在 daemon 模式下会失效
请求 URI 路径会被直接拼到 document_root 后，比如 document_root = /var/www/static + 请求 /css/app.css → 实际查 /var/www/static/css/app.css
static_handler_locations 是白名单路径前缀，不在列表里的请求哪怕文件存在也不会触发静态处理
如果 on('request') 回调里写了 $response->end() 或提前 return，会覆盖掉静态处理器逻辑

`sendfile()` 和 `enable_static_handler` 的本质区别

两者都用内核 sendfile 系统调用实现零拷贝，但触发时机和控制粒度完全不同：

Miller CSV TSV JSON 数据处理器

Miller (mlr) 是一个命令行工具，用于查询、整形和重新格式化名称索引数据，如 CSV、TSV、JSON 和 JSON Lines。它将 awk、sed、cut、join 和 sort 的功能整合到一个专为结构化数据处理而构建的单一工具中。

下载

enable_static_handler 是 Swoole 内置的自动路由：收到请求 → 检查文件是否存在 → 自动设 header → 调用 sendfile → 结束，全程不进 PHP 用户态
$response->sendfile($path) 是手动控制：你得自己判断路径、检查文件、设置 Content-Type、处理 404，甚至可以加权限校验、记录日志、动态改名（比如 Content-Disposition）
注意：sendfile() 要求文件必须可被进程读取（权限位 + SELinux 上下文），而 enable_static_handler 在失败时只静默返回 404，不会报错

开发期能用，上线前必须关掉

很多团队在 Laravel/Hyperf/Swoole 框架里保留 enable_static_handler => true，只为了本地调试方便。但上线后它会带来三个硬伤：

所有静态请求都占用一个 worker 进程，高并发时直接卡住动态接口（比如 1000 QPS 静态请求 = 1000 个协程被占满）
响应头缺失 Cache-Control、ETag、Accept-Ranges，浏览器无法缓存，每次重刷都是全量下载
不支持 gzip/brotli 压缩，JS/CSS 体积膨胀 60%～70%，首屏加载明显变慢
真正该做的是用 Nginx 的 location ^~ /static/ 精准接管，把 expires、gzip on、add_header 全部配齐

配置项之间有隐含依赖关系

enable_static_handler 不是独立开关，它依赖其他几个配置才能正常工作：

必须同时设置 document_root，否则直接忽略该选项
static_handler_locations 默认为空数组，意味着「所有路径都允许」；但如果显式设置了（比如 ['/assets', '/upload']），那 /js/main.js 就不会走静态处理
worker_num 越大，静态请求并发能力越强，但代价是内存占用线性上升 —— 每个 worker 都要维护自己的文件句柄缓存
PHP 的 open_basedir 如果限制了目录范围，会导致 document_root 路径被拒绝访问，错误不抛出，只默默 404