Beego v2.x 项目必须在 GOPATH/src 下用 bee new 初始化，否则包导入失败、路由不注册、模板不渲染；bee 工具依赖 GOPATH 结构，即使启用 GO111MODULE=on；router.go 需含 init() 注册路由，main.go import 路径须匹配目录，模板须放 views/ 下且 TplName 路径严格一致，控制器须嵌入 web.Controller 并大写方法名。
Beego 项目必须在 GOPATH/src 下用 bee new 初始化，否则包导入失败、路由不注册、模板不渲染——这不是可选项，是硬性路径约定。
bee 工具安装必须配对 GO111MODULE 和 GOPATH 模式
Beego v2.x（包括当前主流的 github.com/beego/beego/v2）和配套 bee 工具仍深度依赖 GOPATH 目录结构。即使你启用了 GO111MODULE=on，bee 的项目生成、热重载、目录扫描逻辑依然按传统 GOPATH 路径解析 import 和文件位置。
- 先确认 GOPATH：
go env GOPATH，常见路径如/home/user/go或C:\Users\xxx\go - 进入
$GOPATH/src目录，不是随便建个文件夹再bee new . - 执行
bee new myapp（不带路径），生成结构必须是$GOPATH/src/myapp/ - 若提示
WARN ▶ 0001 Running application outside of GOPATH，说明当前工作目录不在$GOPATH/src内，bee run可能启动但路由/配置/模板全部失效
bee run 启动失败或 404 的真实原因
bee run 不是简单地调 go run main.go，它会自动加载 conf/app.conf、扫描 routers/router.go、启用模板引擎——任一环节路径错或结构缺，就静默跳过。
- 检查
routers/router.go是否存在且含func init() { beego.Get(...); beego.Router(...) }，漏掉init()函数或写在别处，路由表为空 → 全部 404 - 确认
main.go中import路径与实际目录一致，例如项目叫myapp，则必须是import "myapp/controllers"，不能是"./controllers"或"controllers" -
bee run默认监听:8080，但若conf/app.conf里写了httpport = 9000却没生效，大概率是该文件未被加载——因为beego.LoadAppConfig("ini", "conf/app.conf")没手动调，或路径写成./conf/app.conf（相对路径在 bee run 下不工作）
bee generate controller 生成的代码不能直接用
bee generate controller User 会创建 controllers/user.go，但默认生成的结构体嵌入的是 beego.Controller（v1 风格），而 Beego v2.x 要求使用 web.Controller（来自 github.com/beego/beego/v2/server/web）。
- 手动修改 import：
import "github.com/beego/beego/v2/server/web" - 修改结构体定义：
type UserController struct { web.Controller }，不是beego.Controller - 方法名必须首字母大写 + HTTP 动词，如
func (c *UserController) Get()；小写get()不会被反射识别 - 参数提取要用
c.Ctx.Input.Param(":id")，不是c.GetString("id")（后者只读表单/query 字段）
模板渲染失败时先查三件事
写 c.TplName = "user/profile.html" 却报 template: user/profile.html: no such template，问题几乎总出在路径、命名或启动方式上。
- 模板文件必须放在
views/目录下，且完整路径要和TplName字符串完全一致（大小写敏感），views/user/profile.html≠views/User/profile.html - 如果控制器是
UserController、方法是Get()，Beego AutoRouter 默认尝试找views/user/get.html；想自定义，必须显式赋值c.TplName -
beego.Run()必须被调用；如果只写http.ListenAndServe()或漏掉这句，模板引擎根本不会初始化，TplName被忽略
最易被忽略的点：Beego v2.x 的模块路径已拆分，beego.Controller 是 v1 兼容别名，但 bee 生成器默认不更新 import，得手动切到 web.Controller；不改，编译可能过，运行时控制器方法永远不触发。
