应使用 app.HandleDir() 替代已废弃的 app.StaticWeb()，因后者在 v12+ 中路径解析依赖工作目录易致 404、存在路径遍历风险且无安全剥离；正确写法为 app.HandleDir("/assets", iris.Dir("/opt/myapp/assets"))，需绝对路径、权限正确、加 iris.Dir() 包裹，并配合 systemd 配置 WorkingDirectory 等确保部署稳定。
直接用 app.HandleDir()，别碰 app.StaticWeb() —— 后者在 v12+ 已被标记为 legacy，路径处理不一致，容易 404。
为什么 app.StaticWeb() 会出问题
这个函数在旧版 Iris（v11 及以前）中常用，但 v12 起语义模糊：app.StaticWeb("/static", "./assets") 实际行为依赖当前工作目录，而 systemd 或后台启动时工作目录常为 / 或 /root，导致 ./assets 解析失败。错误现象是浏览器访问 /static/css/app.css 返回 404，curl -I http://localhost:8080/static/css/app.css 确认状态码为 404 而非 500。
更隐蔽的问题是：它不校验路径遍历，比如请求 /static/../../etc/passwd 可能被意外放行（取决于底层 http.Dir 是否开启 clean path 检查）。
-
app.StaticWeb()是快捷封装，内部调用http.FileServer但未做StripPrefix安全剥离，路径映射逻辑不透明 - 官方文档已明确建议迁移到
app.HandleDir()+iris.Dir()组合 - 如果你的项目还用着
app.StaticWeb()，升级到 v12 后首次部署大概率挂静态资源
app.HandleDir() 的正确写法和路径陷阱
必须用绝对路径初始化 iris.Dir()，且确保该路径存在、可读、不含符号链接跳转风险。例如：
app.HandleDir("/assets", iris.Dir("/opt/myapp/assets"))
注意三点：
- 第一个参数
"/assets"是客户端访问的 URL 前缀（如https://example.com/assets/logo.png） - 第二个参数必须是
iris.Dir(...)包裹的绝对路径，不能是字符串"/opt/myapp/assets"—— 否则 Iris 会静默忽略或 panic - 目标目录
/opt/myapp/assets需提前mkdir -p并chown给运行用户（如myapp:myapp），否则 open /opt/myapp/assets: permission denied
常见错误配置：
-
app.HandleDir("/assets", "/opt/myapp/assets")—— 缺少iris.Dir()，编译可能过，但运行时报cannot use string as iris.Handler -
app.HandleDir("/assets", iris.Dir("./assets"))—— 相对路径，在 systemd 下几乎必挂 -
app.HandleDir("assets", iris.Dir("/opt/myapp/assets"))—— URL 前缀漏了/，变成相对路径匹配，导致/assets不生效
如何让静态资源支持缓存与安全头
Iris 默认不加 Cache-Control 或 X-Content-Type-Options，需手动包装 iris.Dir()：
fs := iris.Dir("/opt/myapp/assets")
fs.Compress = true // 启用 gzip/brotli（需客户端支持）
fs.IndexNames = []string{"index.html"} // 访问 /assets/ 时返回 index.html
fs.FileSystem = http.FS(os.DirFS("/opt/myapp/assets")) // 更安全的 FS 封装，自动拦截 ../
app.HandleDir("/assets", fs)
这样能避免 MIME 类型嗅探攻击（X-Content-Type-Options: nosniff 由 http.ServeFile 自动加），也支持压缩传输。若要精细控制缓存，得写中间件：
app.Use(func(ctx iris.Context) {
if strings.HasPrefix(ctx.Request().URL.Path, "/assets/") {
ctx.Header("Cache-Control", "public, max-age=31536000")
ctx.Header("Cross-Origin-Embedder-Policy", "require-corp")
ctx.Header("Cross-Origin-Opener-Policy", "same-origin")
}
ctx.Next()
})
systemd 部署时日志和路径必须配对
即使代码里 app.HandleDir() 写对了，systemd service 文件漏配也会让静态资源“看起来”没加载：
- 缺
WorkingDirectory=/opt/myapp→iris.Dir("./assets")仍会错（哪怕你没这么写，也要防手误） - 缺
StandardOutput=journal和StandardError=journal→ 所有app.Logger().Infof("serving assets from %s", path)都消失，无法确认路径是否被 Iris 正确解析 - 没设
Restart=always和RestartSec=5→ 进程崩溃后静态服务就彻底不可用，且无告警
最简可用 service 片段：
[Service] Type=simple User=myapp WorkingDirectory=/opt/myapp ExecStart=/opt/myapp/myapp StandardOutput=journal StandardError=journal Restart=always RestartSec=5
验证命令：sudo journalctl -u myapp -n 50 --no-pager | grep assets，应看到类似 INFO: Serving static files from /opt/myapp/assets 的日志。
路径硬编码不是终点，真正上线前要把 /opt/myapp/assets 抽成环境变量，比如 ASSETS_PATH，再用 os.Getenv("ASSETS_PATH") 构造 iris.Dir() —— 否则换服务器就得改代码重新编译。
