staticcache中间件启用后自动为静态资源添加cache-control和expires头;仅作用于app.handledir()等暴露的静态文件,不影响路由处理器返回内容;传入负数或零值将禁用缓存。

用 iris.StaticCache 中间件设置静态文件缓存
直接在应用启动时调用 app.Use(iris.StaticCache(24 * time.Hour)) 即可生效,它会自动为所有静态文件响应添加 Cache-Control 和 Expires 头。这个中间件只影响通过 app.HandleDir()、app.Favicon() 或 app.StaticWeb() 等方式暴露的静态资源(如 /assets/js/app.js),对路由处理器返回的内容无效。
StaticCache 的参数陷阱:负数和零值会禁用缓存
传入 time.Duration(比如 -1 或 0)时,iris.StaticCache 会悄悄退化为 NoCache 行为——即强制浏览器不缓存,连“后退/前进”都重新拉取。这不是 bug,是设计如此。常见误操作:
- 写成
iris.StaticCache(0)想“暂时关掉”,结果所有 CSS/JS 都变慢 - 环境变量读取失败导致 duration 为 0,线上缓存失效但日志无提示
- 开发时用
time.Second测试,忘了改回生产值,上线后缓存仅 1 秒
静态路径必须显式注册,否则 StaticCache 不起作用
iris.StaticCache 不会自动拦截所有请求;它只修饰那些已由 Iris 静态服务处理的响应。如果你用 http.FileServer 自定义了静态路由,或把文件放在 ./public 但没调用 app.HandleDir("/static", "./public"),那缓存中间件根本碰不到这些响应。
正确姿势:
- 确保静态目录通过
app.HandleDir("/static", "./static")注册 -
iris.StaticCache必须在app.HandleDir之前或之后全局Use,不能只挂到某个路由 - 路径前缀(如
/static)要和实际访问 URL 一致,否则匹配失败
浏览器仍不缓存?检查响应头是否被覆盖
如果其他中间件(比如自定义安全头、CORS 设置)在 StaticCache 之后执行,并调用了 ctx.Header("Cache-Control", ...) 或 ctx.ResponseWriter().Header().Set("Cache-Control", ...),就会覆盖掉 StaticCache 写入的值。
验证方法:curl -I http://localhost:8080/static/main.css,看返回中是否有 Cache-Control: public, max-age=86400。没有?那就说明有中间件在它之后重写了头——把 StaticCache 放到 Use 链最前面通常能解决。
真正容易被忽略的是:Iris 的静态文件服务本身不校验文件是否存在,404 响应也会被 StaticCache 加上缓存头。用户第一次访问一个不存在的图片,拿到 304 或缓存的 404,之后即使你补上了文件,他依然看到 404,除非清空本地缓存或等过期。











