静态资源路径映射必须用SetStaticPath或StaticDir配置，不能靠路由注册；Beego在路由匹配前截断静态请求，仅支持两种初始化阶段的配置方式，且路径为二进制所在目录的相对路径。
静态资源路径映射必须用 SetStaticPath 或 StaticDir，不能靠路由注册
Beego 不会把静态文件请求当作普通路由处理，GET /static/logo.png 不会进入控制器、也不会触发 BeforeRouter 过滤器。你写再多 beego.Router("/static/*", &MainController{}, "*:Static") 都没用——框架在路由匹配前就截断了请求，直接走内置静态服务逻辑。
正确方式只有两种，且必须在 main() 初始化阶段完成：
-
beego.SetStaticPath("/static", "static")：推荐，语义清晰，支持相对路径 -
beego.BConfig.WebConfig.StaticDir["/static"] = "static"：底层字段赋值，效果相同，但易拼错键名
注意："static" 是 Go 应用启动时的**相对路径**（即从二进制所在目录开始找），不是项目根目录或 GOPATH。若你的静态文件放在 ./public，就得写 SetStaticPath("/static", "public")，而不是 "./public" 或 "/home/user/app/public"。
想用根路径 / 访问静态文件？别改 StaticDir["/"]
直接设 beego.BConfig.WebConfig.StaticDir["/"] = "static" 会导致所有请求（包括 API）都被静态处理器拦截，/api/users 也会返回 404 或直接吐出文件内容——因为 Beego 的静态匹配是前缀最长匹配，"/" 会吃掉一切。
可行方案是用 BeforeRouter 手动接管：
- 只对非 API 路径做透明转发，例如排除
v1/、api/、swagger等前缀 - 用
http.ServeFile显式服务文件，避免和内置静态逻辑冲突 - 示例片段：
func TransparentStatic(ctx *context.Context) {
path := ctx.Request.URL.Path
if strings.HasPrefix(path, "/api/") || strings.HasPrefix(path, "/v1/") {
return
}
file := "static" + path
if strings.HasSuffix(path, "/") {
file += "index.html"
}
http.ServeFile(ctx.ResponseWriter, ctx.Request, file)
}
beego.InsertFilter("/*", beego.BeforeRouter, TransparentStatic)
⚠️ 这个函数里要自己处理 index.html 和目录访问，Beego 默认不自动补 index.html；也别忘了加 os.Stat 检查文件是否存在，否则 404 会变成 500。
保护私有静态资源只能用 beego.BeforeStatic
如果你有类似 /static/users/123/private/report.pdf 这种需登录才能看的文件，千万别在 BeforeRouter 里写鉴权逻辑——它根本不会被调用。
beego.BeforeStatic 是唯一能拦截静态请求的钩子，它在静态文件读取前执行，且只对命中 StaticDir 配置的路径生效：
- 注册时路径必须精确匹配前缀，例如
"/static/users/:id([0-9]+)/private/*" - 参数提取要用
ctx.Input.Param(":id")，不是ctx.Input.Param("id") - 过滤器内可安全调用
beego.GlobalSessions.SessionStart()获取 session - 校验失败直接
ctx.Abort(403)，不要return后继续执行
这个钩子在 Beego 1.x 和 2.x 中行为一致，但文档几乎没提，属于“隐性稳定 API”——别怕用，它是官方源码里明确定义的 iota 常量。
静态文件 404 响应体为空？检查 DirectoryIndex 和文件权限
默认情况下，访问 /static/css/（结尾带斜杠）会返回空响应或 404，不是目录列表。这不是 bug，是 http.ServeFile 的默认行为。
启用目录索引需显式设置：
-
beego.DirectoryIndex = true：开启后，访问目录会列出文件（含链接） -
beego.BConfig.WebConfig.DirectoryIndex = true：配置式写法，效果相同
但更常见问题是 404 实际由文件系统权限导致：Go 进程没权限读 static/ 目录下的子文件，或 SELinux/AppArmor 拦截。验证方式是用 os.Stat("static/test.txt") 在过滤器里手动检查，比猜日志更直接。
