beego.setstaticpath 是运行时高优先级api，支持多次调用且互不干扰；staticdir 是配置项写法，后赋值覆盖前赋值，易因加载顺序出错。推荐统一使用 setstaticpath，避免混用导致配置被忽略。
beego.SetStaticPath 与 StaticDir 的区别和选法
两者都能注册静态资源路径，但行为不同：beego.SetStaticPath 是运行时 API，优先级高、支持多次调用；StaticDir 是配置项写法，需在 conf/app.conf 或代码中提前赋值，且后赋值会覆盖前赋值。实际项目中推荐统一用 SetStaticPath，避免配置项被误覆盖或加载顺序出错。
常见错误是混用：比如在 app.conf 里写了 StaticDir["/static"] = "static"，又在 main.go 里调用 beego.SetStaticPath("/static", "static") —— 后者会生效，前者被忽略，但容易让人误以为配置已生效。
-
SetStaticPath("/css", "static/css")表示访问/css/app.css时，实际读取的是项目根目录下static/css/app.css - 多个调用互不干扰：
SetStaticPath("/images", "static/img")和SetStaticPath("/uploads", "uploads")可共存 - 路径参数必须是相对路径（相对于可执行文件所在目录），不能用绝对路径如
/home/user/myapp/static，否则运行时报错找不到目录
想让前端构建产物（如 Vue dist）走根路径 / 访问怎么办
直接设 SetStaticPath("/", "static/dist") 不行 —— Beego 会把所有请求（包括 API 路由）都当成静态文件处理，导致 /api/login 返回 404 或直接吐出文件内容。正确做法是用过滤器劫持非 API 路径，再手动调用 http.ServeFile。
典型实现如下（放在 main.go 的 beego.Run() 之前）：
func TransparentStatic(ctx *context.Context) {
if strings.HasPrefix(ctx.Request.URL.Path, "/api/") ||
strings.HasPrefix(ctx.Request.URL.Path, "/v1/") ||
strings.HasPrefix(ctx.Request.URL.Path, "/swagger/") {
return
}
filePath := "static/dist" + ctx.Request.URL.Path
if ctx.Request.URL.Path == "/" {
filePath = "static/dist/index.html"
}
http.ServeFile(ctx.ResponseWriter, ctx.Request, filePath)
}
beego.InsertFilter("/*", beego.BeforeRouter, TransparentStatic)
注意点：
- 必须显式排除 API 前缀，否则所有接口请求都会 fallback 到静态文件，且无 404 提示
-
index.html需单独处理，否则访问/会 404（http.ServeFile不自动找 index） - 该方式绕过了 Beego 的静态路由逻辑，所以
EnableStatic = false必须设为true或干脆不设（默认 true），否则过滤器可能被跳过
Nginx 前置时，/static 路径为什么总 404
根本原因不是 Beego 没配对，而是 Nginx location 匹配规则被正则覆盖了。比如你写了 location ~ \.js$ { ... }，它会优先于 location /static/ 匹配所有带 .js 的路径，导致 /static/app.js 根本进不到 alias 规则里。
解决办法只有一条：改用前缀匹配并加 ^~ 强制终止后续正则检查：
location ^~ /static/ {
alias /data/www/static/;
expires 1y;
add_header Cache-Control "public, immutable";
}
关键细节：
- 必须用
alias，不是root；alias /data/www/static/（末尾斜杠不能少），否则请求/static/js/app.js会去找/data/www/static/static/js/app.js - Beego 端要关掉静态服务：在
conf/app.conf中加EnableStatic = false，否则 Nginx 和 Beego 可能同时响应，造成缓存头冲突或响应体错乱 - 如果静态文件名含哈希（如
app.a1b2c3.js），务必加immutable，否则某些浏览器不会复用缓存
静态文件返回 404 但路径明明存在，怎么排查
先确认是不是大小写或路径拼写问题 —— Beego 默认区分大小写，/CSS/app.css 和 /css/app.css 是两个路径。更隐蔽的问题是 Go 工作目录不等于项目根目录：当你用 go run main.go 启动时，工作目录是当前 shell 所在路径；但用编译后的二进制启动时，工作目录是二进制所在路径。如果 SetStaticPath("/static", "static") 中的 "static" 是相对路径，就可能指向错位置。
快速验证方法：
- 在
main.go开头加log.Println("wd:", os.Getwd())，看实际工作目录在哪 - 用
os.Stat("static")检查目录是否存在，避免依赖“应该存在”的假设 - Beego 日志级别调到
Debug，它会在控制台打印静态文件查找过程，例如[DEBUG] static file not found: static/js/app.js - 如果用了
DirectoryIndex = true却看不到目录列表，检查是否启用了beego.DirectoryIndex（不是配置项，是全局变量）：需在main.go中写beego.DirectoryIndex = true
最常被忽略的是：Beego 的静态路由只处理 GET 和 HEAD 请求，如果你用 curl -X POST /static/test.txt 测试，它永远 404 —— 这不是 bug，是设计如此。
