Beego 本身不负责生产级静态资源托管，必须交由 Nginx 或 CDN 承担；仅靠 SetStaticPath 或 StaticDir 配置在上线后必然出问题。因./static为相对路径、无法读取环境变量、缺乏ETag/gzip等标准缓存与压缩支持，且Nginx需配置location ^~ /static/、alias及关闭EnableStatic才能正确代理。
直接结论：Beego 本身不负责生产级静态资源托管，必须交由 Nginx 或 CDN 承担；仅靠 SetStaticPath 或 StaticDir 配置，在上线后必然出问题。
为什么 SetStaticPath 在生产环境会失效
很多人在 main.go 里写 web.SetStaticPath("/static", "./static")，开发时能访问 /static/css/app.css，但部署后常出现 404。这不是代码写错了，而是三个现实约束没被满足：
-
./static是相对路径，打包成二进制后运行位置一变（比如放在/opt/myapp），Go 进程就找不到该目录 -
SetStaticPath无法读取环境变量或配置文件，硬编码路径导致多环境（dev/staging/prod）无法复用 - Beego 的
http.ServeFile不支持ETag、Last-Modified、gzip/brotli 压缩等标准缓存与传输优化，浏览器反复拉全量 JS/CSS
Nginx location 配置必须满足的三个条件
假设你把构建产物统一放在 /data/www/static，Beego 后端监听 127.0.0.1:8080，Nginx 做反向代理。以下三者缺一不可：
- 用
location ^~ /static/，不是location /static/—— 否则可能被后续正则location ~* \.js$覆盖，失去最高优先级 - 必须用
alias /data/www/static/（注意末尾斜杠），不能用root——root会拼出/data/www/static/static/css/app.css，导致 404 - 显式关闭 Beego 静态路由：在
conf/app.conf中设EnableStatic = false，否则请求可能被 Beego 先截走，绕过 Nginx 缓存逻辑
location ^~ /static/ {
alias /data/www/static/;
expires 1y;
add_header Cache-Control "public, immutable";
}
前端构建产物该往哪放、怎么引用
Beego 没有前端脚手架，static 目录是服务入口，不是构建输出目录。直接把 Vue/Vite 的 dist 整个拷进 static/ 会导致热重载失效、哈希文件无法匹配、模板路径错乱。
- 构建时应将
outDir设为static/dist（例如 Vite 的build.outDir = "static/dist"），保留static/原有结构 - 模板中引用必须用
{{.StaticUrl}}/dist/app.[hash].js，而非硬写/static/dist/...——{{.StaticUrl}}会自动适配app.conf中的StaticUrl配置（如 CDN 地址） - 若需 SPA history 模式兜底，Nginx 需额外加
try_files $uri /index.html到location ^~ /static/dist/块内，避免刷新 404
需要权限控制的静态路径怎么拦截
比如要限制 /static/users/123/private/report.pdf 只能由用户 123 自己下载，不能用 beego.BeforeRouter —— 静态请求根本不会进入路由阶段，过滤器压根不触发。
- 必须用
beego.BeforeStatic注册过滤器，这是唯一在静态文件处理器执行前介入的钩子 - 路径注册要带正则参数：
beego.InsertFilter("/static/users/:id([0-9]+)/private/*", beego.BeforeStatic, controllers.ProtectPrivateUploads) - 过滤器内需手动启动 session：
sess, _ := beego.GlobalSessions.SessionStart(ctx.ResponseWriter, ctx.Request)，再校验userID与 URL 中提取的:id是否一致
最容易被忽略的是：Beego 的静态资源处理是「短路式」的——一旦命中 StaticDir 或 SetStaticPath 规则，后续所有中间件、控制器、甚至 BeforeExec 都不再执行。所以权限、日志、审计这类逻辑，要么提前塞进 BeforeStatic，要么彻底交给 Nginx（如用 auth_request 模块）。
