Beego是需主动集成的MVC框架，不兼容http.ServeMux即插即用；v2版必须使用github.com/beego/beego/v2路径，通过web.BeeApp.Handlers挂载到现有HTTP服务，并显式配置静态文件、模板路径及日志。
beego 不是“安装”就能用的库，而是需要主动集成进现有 Go 项目的框架。它不兼容标准 http.ServeMux 的即插即用模式，必须接管请求分发链路。如果你已有项目（比如用 net/http 自建路由或用了其他轻量框架），直接 go get 并不能让 beego 自动生效。
确认 Beego 版本与模块路径是否匹配
当前活跃维护的是 beego/v2，导入路径必须为 github.com/beego/beego/v2。旧版 github.com/astaxie/beego 已停止维护，且与 Go Modules 兼容性差，容易触发 missing go.sum 或版本冲突。
- 检查
go.mod中是否已存在旧版引用：若有github.com/astaxie/beego v1.x，先执行go get github.com/beego/beego/v2@latest - 手动替换所有
import "github.com/astaxie/beego"为import "github.com/beego/beego/v2/server/web"（控制器）、"github.com/beego/beego/v2/core/logs"（日志）等子包 - 旧版的
beego.Router在 v2 中已移至web.Router，调用方式不变但包路径必须更新
手动注册 Beego 路由并接入现有 HTTP Server
Beego v2 默认不启动独立 server，而是提供 web.BeeApp.Handlers（一个 http.Handler 实例），你可以把它挂到任意 http.Server 上，也可以和原有路由共存——但要注意顺序和路径前缀冲突。
- 在项目启动处初始化 Beego：调用
web.BeeApp.RunMode = "dev"、web.BeeApp.ListenAddr = ":8080"等配置（非必须，仅当你要用web.BeeApp.StartServer()启动时才需设） - 显式注册控制器路由（避免依赖 AutoRouter 的目录约定）：
web.Router("/api/user", &controllers.UserController{}, "get:Get;post:Post") - 若想复用现有
http.ServeMux，可将web.BeeApp.Handlers作为子 handler 挂载：mux.Handle("/api/", http.StripPrefix("/api", web.BeeApp.Handlers)) - 注意：Beego 的
Handlers会处理完整路径，StripPrefix必须匹配，否则/api/user进入后变成/user才能被Router("/user")匹配
静态文件和模板路径要显式指定
Beego 不会自动扫描 static/ 或 views/ 目录。如果你的项目已有这些目录，必须手动告诉 Beego 它们在哪，否则 c.TplName 渲染失败或 /static/css/app.css 返回 404。
- 设置静态文件映射：
web.SetStaticPath("/static", "./static")（第一个参数是 URL 前缀，第二个是磁盘路径） - 设置模板路径：
web.AddTemplateExt("html")+web.AddViewPath("./views")；模板文件名必须严格符合views/{controller}/{action}.html规则 - 如果原项目用的是
html/template自定义渲染，不要混用：Beego 的c.TplName和c.Render()是一套独立逻辑，和标准库template.ParseFiles互不感知 - 常见坑：
./static是相对当前工作目录（os.Getwd()），不是相对于main.go所在目录；建议用绝对路径或filepath.Join(filepath.Dir(os.Args[0]), "static")
Beego 日志与你原有日志系统怎么共存
Beego v2 的日志模块（core/logs）默认会接管 log 标准库输出，并覆盖 fmt.Println 行为。如果你已有 zap、zerolog 或自定义 logger，必须禁用 Beego 日志初始化，否则出现双写、panic 或格式错乱。
- 在
init()或主函数开头加：web.BeeApp.LogLevel = web.LevelOff，再调用logs.Reset()清空默认 writer - 如需保留 Beego 内部日志（比如 ORM SQL 日志），可单独配置：
logs.SetLogger(logs.AdapterConsole, `{"level":1}`)，但别让它和你的 logger 写同一个io.Writer - Beego 的
c.Ctx.Input.Log是 request-scoped logger，底层仍走core/logs，所以只要全局日志关了，它也不会打屏
Beego 集成最易被忽略的一点：它不是“加个中间件”，而是“换掉路由中枢”。哪怕只用它处理几个 API 路径，也要确保它的 Handler 被正确挂载、路径前缀无歧义、静态/模板路径显式声明——否则错误往往静默发生（比如 404 却没日志，或模板渲染空白）。
