bee new 必须在 $gopath/src 下执行，否则包导入失败、路由不注册、模板找不到；需显式注册路由、严格匹配模板路径与数据字段名，且控制器须正确嵌入 web.controller 并遵循方法命名规范。
bee new 必须在 $GOPATH/src 下执行，否则包导入失败、路由不注册、模板找不到
Beego 项目不是“随便建个目录就能跑”。它的工具链（尤其是 bee）仍深度依赖 Go 的传统 GOPATH 工作区模型。即使你启用了 go mod，bee new 仍会按 $GOPATH/src/yourproject 推导包路径和 import 路径。
常见错误现象：
-
cannot find package "myapp/controllers"：main.go 里 import 的路径无法被 Go 解析 -
bee run启动后访问/显示 Beego 默认欢迎页：说明routers/router.go没生效，本质是包没加载成功 - 模板渲染报
template: index.tpl: no such template：views 目录存在，但控制器根本没被调用，数据压根没传过去
实操建议：
- 运行
go env GOPATH确认输出是一个真实存在的路径（如/home/user/go） -
cd $GOPATH/src，再执行bee new myapp - 不要先
mkdir myapp && cd myapp && bee new .—— 这会导致包路径错乱，bee无法生成正确的 import 路径
beego.Router 是显式注册路由的唯一可靠方式
Beego 不会自动扫描 controllers/ 下所有结构体并绑定路由。AutoRouter 仅在极简 demo 场景下启用，且要求严格满足命名+嵌入+目录约定；生产项目必须靠 routers/router.go 中的 beego.Router 或 beego.Get 显式注册。
常见错误现象：
- 写好了
MainController.Get()，但访问/没反应 - 修改了控制器方法，
bee run后仍是旧行为（热重载没触发，因为路由根本没注册）
实操建议：
- 确保
routers/router.go的init()函数中包含类似语句：beego.Router("/", &controllers.MainController{}) - 参数必须是控制器指针（
&controllers.XxxController{}），不是类型名（controllers.XxxController）或实例（controllers.XxxController{}） - 若只需响应 GET，用
beego.Get("/", func(ctx *context.Context) { ... })更轻量，也绕过控制器生命周期
c.Data 和 c.TplName 配合使用时路径与字段名必须严格匹配
Beego 模板渲染不是“把变量塞进去就完事”，它对路径、命名、大小写全敏感。出错时通常不是语法问题，而是约定断裂。
常见错误现象：
-
c.TplName = "index.tpl"报错找不到模板：实际文件在views/admin/index.tpl，应写"admin/index.tpl" - 模板里写
{{.User.Name}}，但控制器只写了c.Data["user"] = u→ 应写c.Data["User"] = u或模板改用{{.user.Name}} - 修改了
conf/app.conf里的templateleft却没重启bee run，导致{{不被识别为起始标签
实操建议：
- 模板路径 =
views/+ 相对路径（如"user/profile.tpl"对应views/user/profile.tpl） -
c.Data的 key 名直接映射到模板中的.Key，大小写完全一致 -
conf/app.conf修改后必须重启bee run，热重载不监听配置文件变更
beego.Controller 嵌入和方法签名是反射注册的硬性前提
Beego 通过反射识别控制器，不是靠接口实现或继承。漏掉任一条件，整个结构体就被忽略。
容易被忽略的点：
- 必须用
web.Controller（v2 版本路径是github.com/beego/beego/v2/server/web），不是旧版beego.Controller - 方法必须首字母大写，且以 HTTP 动词开头：
Get()、Post()、Delete()——get()或HandleGet()都无效 - 控制器文件必须放在
controllers/目录下，且包名必须是controllers
最简可用示例：
package controllers
<p>import "github.com/beego/beego/v2/server/web"</p><p>type MainController struct {
web.Controller
}</p><p>func (c *MainController) Get() {
c.Data["Message"] = "Hello Beego"
c.TplName = "index.tpl"
}
</p>
路径、包名、嵌入、方法名、路由注册、模板路径——这六个点只要一个断掉，Beego 就静默失效，不会报错，只会返回 404 或默认页。新手卡住，90% 是栽在这串隐性链条上。
