Iris静态文件必须显式注册，不能自动发现；需用StaticWeb或HandleDir指定URL与磁盘路径映射，且必须置于所有业务路由之前，否则404。
不配 HandleDir 或 StaticWeb，浏览器直接 404；配错路径或顺序，CSS/JS 加载失败但控制台没报错——这是最常被忽略的部署断点。
静态文件目录必须显式注册，不能靠约定自动发现
Iris 不会扫描 ./static 或 ./public 这类常见目录。你得明确告诉它“哪个 URL 路径映射到哪个磁盘路径”。
-
app.HandleDir("/assets", iris.Dir("./assets"))表示：访问/assets/main.css时，Iris 去找本地./assets/main.css -
app.StaticWeb("/static", "./static")是等价写法，但语义更清晰：把./static整个目录挂载为 Web 可访问的/static根路径 - 路径是相对工作目录（
go run所在位置）的，不是相对于main.go的——交叉编译后这点尤其容易出错
HandleDir 和 StaticWeb 的行为差异
两者都能服务静态文件，但底层逻辑不同：
-
HandleDir是通用目录处理器，支持自定义IndexName（比如设为"index.html"），也支持隐藏文件过滤（通过iris.DirOptions） -
StaticWeb是专为静态资源优化的快捷方法，内置缓存头（Cache-Control）、gzip 支持，且自动拒绝访问..路径（防目录遍历） - 如果只是放 CSS/JS/图片，优先用
StaticWeb；需要定制索引页或权限逻辑，才选HandleDir
路由顺序决定静态文件能否被正确拦截
Iris 按注册顺序匹配路由。如果你把 app.Get("/{param:path}", ...) 这种兜底路由写在 StaticWeb 前面，所有请求都会被它吃掉，静态文件永远 404。
- 必须把静态配置放在所有业务路由之前，例如：
app.StaticWeb("/static", "./static")→app.Get("/", ...)→app.Post("/api", ...) - 模板里引用静态资源时，路径要和注册的 URL 前缀一致：
<link href="/static/css/app.css">，而不是/css/app.css - 开发时加
tmpl.Reload(true)不影响静态文件，但别误以为它能热更 CSS——那是浏览器缓存的事，需手动刷新或禁用缓存
生产环境要注意 MIME 类型和缓存头
默认情况下，StaticWeb 对常见后缀（.js、.css、.png）返回正确 Content-Type，但遇到 .webp、.woff2 等新格式可能返回 text/plain，导致浏览器拒绝加载。
- 可手动注册扩展名：
iris.RegisterExtension("webp", "image/webp") - 缓存策略由
StaticWeb自动设置（max-age=31536000for assets），但 HTML 模板不应缓存——所以别把.html放进StaticWeb目录，它该走View渲染 - 反向代理（如 Nginx）若启用了缓存，会覆盖 Iris 的响应头，这时得在 Nginx 配置里显式清除或改写
Cache-Control
真正麻烦的从来不是怎么写那两行代码，而是当页面白屏、F12 看 Network 里全是 404 时，你得意识到：问题不在前端代码，也不在 Go 逻辑，而在那一行 StaticWeb 是否在正确位置、路径是否对得上当前工作目录、以及浏览器地址栏里敲的 URL 前缀有没有和注册的一致。
