StaticFile中间件默认不拦截图片请求，但会拒绝访问以/.开头的隐藏文件；图片404主因是路径匹配失败或响应头缺失，非拦截导致。
StaticFile中间件默认行为会拦截图片请求吗
不会自动拦截，但默认配置里有一条隐藏文件防护逻辑：if(strpos($request->path(),'/.') !== false)，这会导致访问 /images/.gitignore 或 /css/.DS_Store 这类路径被拒绝。真正影响图片/CSS加载的，是路径匹配和响应头缺失，不是拦截本身。
常见错误现象包括：图片 404（实际文件存在）、CSS 不生效（MIME 类型错误）、浏览器反复请求资源（缺少缓存头）。
- 确认
public/是 Web 服务器 DocumentRoot，Webman 的StaticFile中间件只处理未被 Nginx/Apache 直接响应的请求 - 检查
app/middleware/StaticFile.php中的$allowed_extensions是否包含.jpg、.png、.css等后缀 - 确保中间件在
config/middleware.php中已启用且顺序靠前（不能被其他中间件提前终止）
如何给静态资源添加 Cache-Control 和 ETag
Webman 默认不自动设置强缓存头，必须手动扩展 StaticFile 中间件。否则每次刷新都会触发 200 响应，浪费带宽和时间。
实操建议：在 app/middleware/StaticFile.php 的 process() 方法末尾插入：
立即学习“前端免费学习笔记（深入）”；
if ($response->getStatusCode() === 200) {
$path = $request->path();
$ext = pathinfo($path, PATHINFO_EXTENSION);
if (in_array($ext, ['js', 'css', 'jpg', 'jpeg', 'png', 'gif', 'webp'])) {
$response = $response->withHeader('Cache-Control', 'public, max-age=31536000, immutable');
$response = $response->withHeader('ETag', '"' . md5_file($file) . '"');
}
}-
immutable表示该资源永不变更，可防止浏览器在max-age内发起条件请求 - 避免对 HTML 或带查询参数的资源（如
logo.png?v=1.2）加immutable，否则更新后用户无法及时获取 - 生成
ETag用md5_file()比时间戳更可靠，但注意大文件会轻微拖慢首次响应
Nginx 代理下 StaticFile 中间件还起作用吗
基本不起作用 —— 如果你把 Nginx 配置成直接服务 public/ 下所有静态文件（推荐做法），那么请求根本不会到达 PHP 层，StaticFile 中间件完全被绕过。
典型 Nginx 配置片段（放在 server 块内）：
location ~* \.(js|css|png|jpg|jpeg|gif|webp|ico|svg|woff2?|ttf|eot)$ {
root /path/to/your/project/public;
expires 1y;
add_header Cache-Control "public, immutable";
add_header X-Static "nginx";
}- 这种配置下，PHP 进程零负担，加载速度由磁盘 I/O 和网络决定，比走 PHP 中间件快 3–5 倍
- 如果仍想用
StaticFile（比如需要动态鉴权或日志统计），需注释掉 Nginx 的静态规则，并确保location /转发到 PHP-FPM - 注意：Nginx 的
root必须指向public/目录，不是项目根目录，否则路径拼接会出错
为什么加了版本哈希后图片仍不更新
因为浏览器缓存了旧 URL，而新 URL（如 logo.a1b2c3.png）没被请求过。Webman 本身不生成哈希，需要构建时处理或模板中注入。
两种常用方式：
- 前端构建（如 Webpack/Vite）输出带 contenthash 的文件，并通过
manifest.json映射原始名 → 哈希名，在 Webman 视图中读取并渲染正确路径 - 在 Webman 的
view模板中用辅助函数生成带时间戳或版本号的 URL：<img src="/images/logo.png?v={{ config('app.version') }}">，但这种方式不支持长期缓存 - 绝对不要依赖
filemtime()动态拼接 URL，它会在每次请求时触发系统调用，严重拖慢响应
最易被忽略的一点：CDN 或反向代理可能缓存了旧的 HTML 页面，导致里面写的还是旧资源链接 —— 更新静态资源后，务必连带清理 HTML 缓存层。
