app.staticweb 是 iris 官方推荐且最稳定的静态资源服务方式，用于将本地目录映射为 web 可访问路径，支持缓存、etag、range 等生产特性，需注意前缀不能为 "/"、路径需与前端 publicpath 一致、避免被反向代理干扰，并配合 get 兜底路由处理 spa。
app.StaticWeb 是设置静态资源路径的正确方式
直接调用 app.StaticWeb 即可将本地目录映射为 Web 可访问路径，这是 Iris 官方推荐且最稳定的静态资源服务方式。它内部使用的是高效文件服务器，支持缓存头、ETag、Range 请求等生产必需特性。
常见错误是误用 Party.HandleDir 或手动写 ctx.ServeFile ——前者主要用于嵌入式文件系统或特殊路由分组场景，后者无法自动处理目录索引和 MIME 类型推导，容易导致 CSS/JS 加载失败或 404。
-
app.StaticWeb("/static", "./assets")表示：浏览器访问/static/css/main.css时，Iris 会从当前工作目录下的./assets/css/main.css读取并返回 - 路径前缀（第一个参数）不能是
"/"，否则会覆盖所有其他路由；Iris 明确禁止app.StaticWeb("/", "./public") - 第二个参数必须是相对或绝对文件系统路径，不支持嵌入资源（如
embed.FS），需用app.StaticEmbedded替代
子路径部署时 publicPath 和 StaticWeb 前缀必须一致
前端构建工具（如 Vue CLI、Vite）生成的 index.html 中，资源引用路径由 publicPath 决定。如果构建时设了 publicPath: "/app/"，那所有 JS/CSS 的 src 或 href 都会带 /app/ 前缀——此时后端 StaticWeb 的挂载路径也必须匹配，否则 404。
- 构建配置
publicPath: "/app/"→ 后端必须用app.StaticWeb("/app", "./dist") - 若构建用
publicPath: "/"，但实际部署在 Nginx 的location /myapp/ { proxy_pass http://localhost:8080/; }下，则前端资源请求会变成/myapp/static/xxx.js，后端就得配app.StaticWeb("/myapp/static", "./dist/static") - 验证方法：curl
http://localhost:8080/app/static/main.js应返回 JS 文件内容，状态码 200；若返回 404 或 HTML 页面，说明路径不匹配或被其他路由劫持
SPA 场景下别让 StaticWeb 拦截 HTML 路由
单页应用需要把所有非静态资源请求 fallback 到 index.html，但 app.StaticWeb 本身不具备 fallback 能力。如果只配了 StaticWeb 又没关掉默认行为，可能意外拦截掉本该由前端路由处理的路径（比如 /user/profile）。
- 先禁用 Iris 默认的静态服务：确保没调用
app.StaticWeb以外的静态相关方法（如app.StaticEmbedded、app.Favicon的副作用路径），尤其避免重复注册相同前缀 - 用通配路由兜底：在所有
StaticWeb之后加一条app.Get("/{p:path}", func(ctx iris.Context) { ctx.ServeFile("./dist/index.html") })，注意顺序——必须放在最后 - 关键限制：这个兜底路由不能写成
app.Any("/{p:path}")，否则会劫持 POST/PUT 等 API 请求；仅GET是安全的
静态资源路径不生效的三个高频原因
90% 的路径问题不是代码写错，而是环境或配置细节被忽略。
- 工作目录不对：Go 运行时的
./assets是相对于执行命令所在路径，不是源码目录。用os.Getwd()打印确认，或改用绝对路径（如filepath.Join(os.Getenv("HOME"), "myapp", "assets")） - 文件权限或大小写敏感：Linux 下
main.CSS≠main.css，而浏览器请求的是小写路径；确保磁盘文件名与 HTML 中引用的完全一致 - 反向代理干扰：Nginx/Apache 若已配置
location /static，就不要再让 Iris 处理这部分请求，否则可能因路径重写或缓存策略冲突导致 404 或 502
curl -I 检查响应头中的 Content-Type 和 Content-Length，比看页面是否显示更可靠。
