beego适合快速交付后台系统，但易卡在路由映射、orm初始化、静态资源路径三处：需确保conf/app.conf与go.mod版本匹配、注册模型并调用runsyncdb、手动注册路由且控制器必须嵌入beego.controller。
Beego 适合快速交付功能完整的后台系统，但直接上手容易卡在路由映射、ORM 初始化、静态资源路径这三处——不是框架不行，是它“开箱即用”的默认行为和你本地环境常有隐性冲突。
bee run 启动失败：检查 conf/app.conf 和 go.mod 是否匹配
常见错误现象是 bee run 报错 undefined: beego.BConfig 或 cannot find package "github.com/beego/beego/v2"。这不是代码写错了，而是版本对不上。
- Beego v2 要求项目必须启用 Go Modules，
go.mod中必须明确声明require github.com/beego/beego/v2 v2.3.4（以实际最新稳定版为准） -
conf/app.conf里不能写appname = beego这种占位名，得改成你的真实项目名，否则bee工具无法正确加载配置 - 如果用的是
beego-admin这类开源模板，注意它可能基于 v1.x，而新装的bee默认拉 v2，此时应统一降级：go get github.com/beego/beego/v1@v1.12.5
ORM 查询总是返回空：别跳过 RegisterModel 和 RunSyncdb
很多新手写了 models.User 结构体、也调了 o.Read(&u, "id")，但始终查不到数据——根本原因是没注册模型，或数据库表根本不存在。
- 必须在
models/models.go的init()函数里显式调用orm.RegisterModel(new(User))，仅定义结构体不生效 - 开发阶段建议开启自动建表：
orm.RunSyncdb("default", false, true)放在main.go的beego.Run()之前；false表示不删除已有表，true表示自动创建缺失表 - MySQL 连接字符串里如果含特殊字符（如
@、/），必须 URL 编码，例如密码p@ss/wd要写成p%40ss%2Fwd
前端请求 404 或 502：确认路由注册方式与控制器嵌入关系
后端写了 controllers.AdminController，前端访问 /admin/list 却 404，大概率是路由没绑对，或控制器没按 Beego 规范嵌入。
- 不要依赖自动路由（
beego.AutoRouter(&controllers.AdminController{})），它只认方法名首字母大写 + HTTP 方法名组合（如GetList→GET /admin/list），且要求结构体字段全部导出；手动注册更可控：beego.Router("/admin/list", &controllers.AdminController{}, "get:List") - 自定义控制器必须嵌入
beego.Controller，且不能是匿名字段以外的形式，例如type AdminController struct { Ctx *context.Context }是无效的，必须是type AdminController struct { beego.Controller } - 如果用了 Nginx 反向代理，注意 Beego 默认不处理
X-Forwarded-For，需在conf/app.conf加EnableXSRF = true并设置TrustProxy = true才能正确识别真实 IP
最易被忽略的一点：Beego 的 views 模板默认不支持 Vue 的 {{ }} 插值语法，因为和 Beego 自身模板语法冲突。要么改 Vue 为使用 v-text 指令，要么在模板顶部加 {{/* 关闭 Beego 解析，否则页面会直接渲染出未编译的 {{item.name}} 字符串。
