静态文件请求绕过路由匹配，beforerouter不生效；应使用beego.beforestatic过滤器、注意staticdir注册顺序、确保html路径与go注册前缀一致，并在测试中显式导入routers包。
静态文件请求直接绕过路由匹配，BeforeRouter 过滤器不生效
Beego 对 /static/ 类路径的处理是短路式的：一旦请求路径命中 beego.StaticDir 配置的目录，框架就跳过整个路由树匹配流程，不走控制器、不触发 BeforeRouter 或 BeforeExec。这意味着你在这些钩子里写的权限校验、日志记录、参数解析，对静态资源请求完全无效。
常见错误现象包括：
- 在
BeforeRouter里检查用户登录态，但访问/static/private/file.pdf仍能直连下载 - 想给静态路径加 CORS 头，却只在控制器里写
c.Header("Access-Control-Allow-Origin", "*")，结果没生效
✅ 正确做法是使用 beego.BeforeStatic 过滤点。它专为静态请求设计，在文件读取前调用，且支持路径正则匹配：
beego.InsertFilter(
"/static/users/:id([0-9]+)/private/*",
beego.BeforeStatic,
controllers.ProtectPrivateUploads,
)
注意：:id 后必须跟正则约束（如 ([0-9]+)），否则匹配会失败；过滤器函数内需手动调用 ctx.Abort() 终止后续处理。
beego.SetStaticPath 和 beego.StaticDir 的注册顺序影响路径覆盖
Beego 允许多次调用 SetStaticPath 或配置多个 StaticDir，但内部按注册顺序依次尝试匹配——第一个匹配成功的路径即被采用，后续注册的同前缀路径不会生效。
容易踩的坑：
- 先注册
SetStaticPath("/static", "./assets")，再注册SetStaticPath("/static/js", "./dist/js")：后者永远不会被触发，因为/static/xxx总是先被前者捕获 - 两个
StaticDir都配置了/public前缀，但实际文件分布在不同磁盘路径，结果只加载了第一个注册的目录
验证方式：启动后查看 Beego 日志中类似 [INFO] Static path registered: /static -> ./assets 的输出，确认你期望的映射是否出现在最前面。
HTML 中引用路径与 Go 注册前缀不一致导致 404 或内容错乱
静态资源 404 的本质不是文件不存在，而是浏览器请求路径、Go 路由注册前缀、本地文件系统路径三者未对齐。典型表现是：CSS 文件返回的是 HTML 页面内容（比如 index.html），而不是样式代码。
当代理已经知道网站路由或内容URL，并且在启动前需要有效的sitemap XML、sitemap索引或robots.txt引用时，请使用sitemap。这是一个发布构件技能，而不是爬虫或SEO平台。
原因通常是：
- HTML 写了
<link href="/css/main.css">，但 Go 里注册的是SetStaticPath("/static", "./public")→ 浏览器请求/css/main.css根本没进静态处理器，被 API 路由或NoRoute拦截 - Go 注册了
SetStaticPath("/static/", "./public")（带尾斜杠），而 HTML 引用的是/static/css/main.css（不带尾斜杠）→ Beego 内部路径规范化可能失败，匹配不到 -
http.Dir("./public")指向错误目录，比如实际文件在./dist/public，却写了"./public"
✅ 解决方案：统一用无尾斜杠前缀 + 绝对路径引用。例如：
beego.SetStaticPath("/static", "./dist/public")
// HTML 中写
<link href="/static/css/main.css">
测试环境下静态路径失效，是因为路由模块未被导入
Beego 单元测试中，/static/xxx 返回 404 不是配置错了，而是整个静态路径注册逻辑根本没执行——因为 routers/router.go 中的 init() 函数依赖包导入触发，而测试文件默认不导入该包。
现象：
- 运行时一切正常，
bee run下静态文件可访问 - 执行
go test时，所有静态路径都 404，beego.BConfig.StaticDir为空
✅ 必须在测试文件顶部显式导入路由包（即使不直接使用）：
import (
_ "your-app/routers"
)
这个空白导入会强制执行 routers/init()，从而完成 SetStaticPath 等注册。漏掉这行，整个静态服务在测试中就是关闭状态。
真正难排查的不是路径写错，而是静态请求根本不经过你熟悉的那套生命周期——它有自己的通道，自己的过滤点，自己的注册时序。盯住 BeforeStatic、核对注册顺序、强制导入路由包，这三件事做对了，80% 的静态冲突就消失了。
