enable_static_handler不生效的主因有三：document_root未用绝对路径、static_handler_locations白名单未匹配请求URI前缀、on('request')中提前end()覆盖静态处理逻辑。
enable_static_handler 为什么总不生效
开了 enable_static_handler 却还是进 on('request') 回调，或者返回 404，根本原因就三条：
-
document_root没写绝对路径——比如写成./public或public，在 daemon 模式下会相对于系统根目录找，必然失败 -
static_handler_locations白名单没配对——它只匹配请求 URI 的前缀，例如设为['/static/', '/images/']，那/css/app.css就完全不触发 -
on('request')里提前$response->end()或return了——Swoole 的静态处理器是“尽力而为”，一旦 PHP 层开始响应，它就彻底放弃接管
sendfile() 和 enable_static_handler 的触发时机差异
两者底层都走内核 sendfile() 系统调用，但控制权完全不同：
-
enable_static_handler是 Swoole 内置的自动路由：收到请求 → 拼路径查文件 → 自动设Content-Type和Content-Length→ 调sendfile()→ 结束。全程不进 PHP 用户态，也没机会加日志或权限判断 -
$response->sendfile($path)是你手动控制：得自己解析 URI、检查文件是否存在、校验读权限（注意 SELinux 上下文）、设置 header、处理 404，甚至能动态改Content-Disposition - 关键区别：前者失败只静默返回 404；后者失败会抛异常或返回 false，你能捕获并做 fallback
为什么生产环境必须关掉 enable_static_handler
它不是“轻量版 Nginx”，而是个带硬伤的调试开关：
- 每个静态请求占一个 worker 协程——1000 QPS 的 JS 请求 = 1000 个协程被锁死，动态接口直接卡住
- 不发
Cache-Control、ETag、Accept-Ranges，浏览器没法缓存，每次都是全量下载 - 不支持 gzip/brotli 压缩，JS/CSS 体积膨胀 60%～70%，首屏加载肉眼可见变慢
- 不支持断点续传（Range 请求），大文件下载中断后无法续
Nginx 接管静态文件时的关键配置点
真正该做的，是让 Nginx 在反向代理之前就截住静态请求：
- 用
location ^~ /static/而非location ~ \.js$，避免正则开销，且优先级高于通用规则 -
root必须指向真实磁盘路径，和 Swoole 的document_root保持一致（如/var/www/static） - 缓存头不能只靠
expires：加上add_header Cache-Control "public, immutable"，让现代浏览器真正复用 - 务必开
sendfile on和tcp_nopush on，这是零拷贝和包合并的关键
复杂点在于路径映射必须严丝合缝——Nginx 的 root + location 路径拼接，要和 Swoole 里 document_root + 请求 URI 的拼接逻辑完全对齐，差一个斜杠都会 404。
