Beego项目必须在$GOPATH/src下执行bee new初始化,否则包导入失败、路由不注册、模板不渲染;router.go需在init()中显式注册路由;模板路径与数据字段名须严格匹配;控制器方法须大写首字母并接收*beego.Controller指针。

必须在 $GOPATH/src 下执行 bee new,否则项目结构错乱、包导入失败、路由不注册、模板不渲染——这不是可选项,是硬性路径约束。
bee new 必须在 $GOPATH/src 目录下运行
Beego 的 bee 工具仍基于 GOPATH 模式解析 import 路径和配置文件位置,即使项目有 go.mod,它也只认 $GOPATH/src/myproject 这种结构。
- 错误做法:
mkdir myapp && cd myapp && bee new .→main.go中的import "myapp/controllers"会报cannot find package "myapp/controllers" - 正确流程:先运行
go env GOPATH确认路径(如/home/user/go),然后cd /home/user/go/src,再执行bee new myapp - 验证成功标志:生成的目录是
$GOPATH/src/myapp/,且main.go中的 import 路径(如"myapp/controllers")能与该位置严格对应
router.go 的 init() 函数里必须显式注册路由
Beego 不自动扫描控制器方法,所有路由都得手动写进 routers/router.go 的 init() 函数里。没注册 = 请求直接 404。
- 错误位置:把
beego.Get("/test", ...)写在controllers/文件里、或main.go里 - 正确写法:
routers/router.go中的func init() { beego.Get("/", func(ctx *context.Context) { ctx.WriteString("OK") }) } - 注意参数:用
&controllers.MainController{}(取地址),不是controllers.MainController{}(值类型);若用beego.Router,第三个参数是"get:Get;post:Post"这样的 method:action 映射,不是自由字符串
模板渲染失败?检查三个硬性条件是否同时满足
c.TplName = "index.tpl" 不等于页面能出来。Beego 对路径、字段名、启动方式都有强约定。
- 路径必须存在且大小写一致:
views/index.tpl必须存在;若放views/admin/index.tpl,就得写c.TplName = "admin/index.tpl" - 数据字段名要和模板变量对齐:传
c.Data["Website"] = "beego.dev",模板里就得写{{.Website}},不是{{.Data.Website}} - 必须调
beego.Run():只写http.ListenAndServe()或漏掉这句,模板引擎根本不会启用,TplName被完全忽略
控制器方法命名和接收者类型不能错
Beego 靠反射识别 Controller 方法,任何偏差都会导致方法被跳过——不报错,但静默失效。
- 合法写法:
func (c *MainController) Get() { c.Ctx.WriteString("ok") }(首字母大写 +*beego.Controller指针接收者) - 非法写法:
func (c MainController) get() {}(小写方法名 + 值类型接收者) - 访问 URL 参数要用
c.Ctx.Input.Param(":id"),不是c.GetString("id")(那是表单字段);Prepare()可用于权限校验,但若调了c.StopRun(),后续逻辑必须不再执行
最常被忽略的是:项目目录不在 $GOPATH/src 下时,conf/app.conf 找不到、routers/router.go 不被加载、views/ 路径解析失败——这些都不是配置问题,是路径约定未满足导致的连锁失效。











