Beego 项目必须在 $GOPATH/src 下执行 bee new 初始化,否则 import 路径失效;路由需手动注册到 routers/router.go 的 init() 中;模板渲染要求 views 路径匹配、app.conf 配置正确且 UTF-8 无 BOM;配置仅读取 conf/app.conf(INI 格式),修改后须重启。

Beego 项目跑不起来,90% 是因为没在 $GOPATH/src 下执行 bee new;路由 404、模板不渲染、配置读不到,基本都卡在这几个硬性约定上。
必须在 $GOPATH/src 下初始化项目
Beego 的 bee 工具不认 go.mod,也不支持任意路径创建。它靠 GOPATH 推导包导入路径,一旦脱离 $GOPATH/src,import "myapp/controllers" 就会失败。
- 运行
go env GOPATH确认路径(如/home/user/go) - 终端进入
$GOPATH/src(Linux/macOS)或%GOPATH%\src(Windows) - 执行
bee new myproject,不要加.或绝对路径 - 生成的
main.go中import "myproject/controllers"才能被正确解析
routers/router.go 必须显式注册路由
Beego 不自动扫描控制器方法,所有路由都得手动写进 routers/router.go 的 init() 函数里。只定义结构体、不调 beego.Router,等于没写。
- 确保有类似
beego.Router("/", &controllers.MainController{})的语句 - 传的是指针
&controllers.XxxController{},不是类型名controllers.XxxController - 如果只是返回字符串,用
beego.Get("/", func(ctx *context.Context) { ctx.WriteString("OK") })更轻量 - 别忘了在
main.go中导入_ "myproject/routers"(下划线前缀触发init())
模板渲染要同时满足三个条件
写 c.TplName = "index.tpl" 后报 template: "index.tpl" is undefined,大概率是以下某条没对上:
-
views/index.tpl文件真实存在,且路径大小写完全匹配(比如放在views/admin/下就得写c.TplName = "admin/index.tpl") -
conf/app.conf中templateleft = "{{"和templateright = "}}"未被注释或改错(默认已配好,但改过就得重启bee run) -
main.go中调用了beego.Run()(仅http.ListenAndServe不启用模板引擎) - 模板中访问字段写
{{.Website}},对应代码是c.Data["Website"] = "xxx";字段名首字母必须大写才能导出
配置文件只认 conf/app.conf(INI 格式)
Beego 启动时只加载项目根目录下 conf/app.conf,不识别 JSON/YAML/TOML,也不 fallback 到其他路径。
- 文件编码必须是 UTF-8 无 BOM(Windows 记事本保存易带 BOM,导致解析失败)
- section 名(如
[dev])必须与runmode值严格一致(区分大小写) - 读取自定义 key 时别直接用
beego.AppConfig.String("mysql.host"),应先Exists再DefaultString - 修改
app.conf后必须重启bee run,配置不会热重载
最常被忽略的是:路由注册依赖包导入触发 init(),模板路径和命名强绑定控制器/方法名小写,以及 ORM 模型必须显式 RegisterModel —— 这些不是可选项,是 Beego 运行的硬前提。
golang免费学习笔记(深入):立即使用
在学习笔记中,你将探索golang的核心概念和高级技巧!











