iris.fileserver 返回 404 是因未正确配置路径映射：默认将请求路径（如 /static/style.css）原样拼接至本地目录（得 ./public/static/style.css），但文件实际在 ./public/style.css；须改用 app.staticweb("/static", "./public") 或显式设置 iris.dir("./public").indexname("index.html") 并确保路径对齐。
iris.FileServer 为什么返回 404？
直接用 iris.FileServer 不会自动映射到磁盘路径，它只注册一个路由处理器，但默认不启用目录遍历、也不设置根路径别名——你得显式告诉它“哪个 URL 前缀对应哪个本地文件夹”。常见错误是写了 app.Handle("GET", "/static", iris.FileServer(iris.Dir("./public"))) 却访问 /static/style.css 报 404，因为 iris.Dir("./public") 默认把请求路径原样拼到目录后，而 /static/style.css 实际要去找 ./public/static/style.css，但文件其实在 ./public/style.css。
- 正确做法是加
iris.Options{ShowList: true}并用iris.FileSystem或指定IndexName - 更稳妥的是用
app.StaticWeb("/static", "./public")，它内部已处理好路径剥离逻辑 - 如果必须用
FileServer，要配iris.Dir("./public").IndexName("index.html")，且确保请求路径与文件结构对齐
StaticWeb 和 StaticEmbedded 有什么区别？
app.StaticWeb 读取本地文件系统，适合开发和普通部署；app.StaticEmbedded 从 Go 的 embed.FS 加载，用于打包进二进制——两者 API 相似但底层行为不同。用错会导致运行时 panic 或资源全 404。
-
StaticWeb("/assets", "./dist")：每次请求都打开文件，依赖 OS 文件缓存，适合调试 -
StaticEmbedded("/assets", assetFS, "dist")：需要先//go:embed dist，路径参数"dist"是 embed 中的子目录名，不是磁盘路径 - 嵌入式资源不支持热更新，修改
dist/后必须重新编译 - 若嵌入时用了
os.DirFS混淆，会编译失败或运行时报fs: embedded directory not found
如何让 CSS/JS 修改后浏览器不缓存？
Iris 默认不加 Cache-Control，但浏览器可能基于文件名或响应头缓存静态资源。靠刷新解决不了上线后的用户端问题。
- 开发期可用
app.UseGlobal(iris.Compression) // 自动加 ETag，配合curl -I看是否返回ETag - 生产建议在构建阶段生成带哈希的文件名（如
main.a1b2c3.js），再用StaticWeb，避免手动控制头 - 强行加头：用
app.UseGlobal(func(ctx iris.Context) { ctx.Header("Cache-Control", "no-cache") })，但会影响性能，仅限调试 - 注意：
StaticWeb的响应头由 Iris 内部控制，中间件加的Cache-Control可能被覆盖，优先走构建时哈希方案
下载文件时 Content-Disposition 怎么设？
Iris 没有内置“下载模式”，ctx.ServeFile 默认以 inline 渲染，想触发下载必须手动设头。常见错误是只改 Content-Disposition 却漏了 Content-Type，导致浏览器解析异常或乱码。
- 正确写法：
ctx.Header("Content-Disposition", `attachment; filename="report.pdf"`) ctx.Header("Content-Type", "application/pdf") ctx.ServeFile("./files/report.pdf") - 文件名含中文要用
filename*=UTF-8''xxx编码，Go 标准库没自动处理，得自己调url.PathEscape - 大文件别用
ServeFile，改用ctx.SendFile（底层用io.Copy流式传输） - 路径必须校验，防止
../../../etc/passwd类攻击，iris.Dir有基础防护，但自定义下载逻辑需用filepath.Clean+ 白名单校验
路径拼接和头设置是静态资源最易出错的两个点，尤其混用 embed 和本地路径时，编译期看不出问题，运行才报错。建议所有静态路径统一走构建脚本生成配置，而不是硬编码。
