Beego v2是当前唯一维护版本，新项目必须用github.com/beego/beego/v2路径；安装需go get github.com/beego/beego/v2@latest和go install github.com/beego/bee/v2@latest，且GOPATH/bin须加入PATH，项目需go mod init并下划线导入routers包以注册路由。
Beego v2 是当前唯一值得投入的版本，v1 已停止维护，所有新项目必须用 github.com/beego/beego/v2 路径；bee 工具不装或装错路径，bee new 命令根本跑不起来。
go mod 初始化和 Beego v2 依赖安装
Beego v2 不再是单包导入，必须按模块路径精确引入。直接 go get github.com/astaxie/beego 会拉到已废弃的 v1，后续编译报错或路由不生效都是这个原因。
- 新建项目目录后，先执行
go mod init example.com/myapp（模块名不能以beego开头，否则go mod tidy会冲突） - 然后明确安装 v2：
go get github.com/beego/beego/v2@latest - 如果提示
unknown revision或超时，先设置代理：go env -w GOPROXY=https://goproxy.cn,direct -
go mod tidy后检查go.sum是否包含github.com/beego/beego/v2 v2.开头的行，没出现就说明没装对
bee 工具安装与 PATH 配置失效问题
bee 不是可选工具，它是生成标准目录结构、热重载、自动路由扫描的刚需组件。Windows/macOS/Linux 下最常踩的坑是二进制文件路径没进 PATH，导致终端识别为命令不存在。
- 安装命令必须是：
go install github.com/beego/bee/v2@latest（注意/v2后缀，v1 的github.com/beego/bee已不可用） - 确认安装位置：
go env GOPATH，bee二进制默认落在$GOPATH/bin - Linux/macOS：在
~/.bashrc或~/.zshrc末尾加export PATH=$PATH:$GOPATH/bin，然后source ~/.zshrc - Windows：在系统环境变量
PATH中添加%USERPROFILE%\go\bin（不是Go\bin，那是 Go 自身的 bin） - 验证：
bee version应输出类似v2.1.0，若报'bee' is not recognized，重启终端或重新登录用户
创建项目时 router 注册失败的典型表现
用 bee new myapp 创建的项目，main.go 默认只调 web.Run()，但不会自动加载 routers/router.go —— 这是 v2 和 v1 最隐蔽的差异点，新手常以为“结构生成了就等于能跑”，结果访问 8080 只看到 404。
- 必须手动在
main.go中导入 routers 包：_ "myapp/routers"（注意下划线导入，触发init()函数注册路由） - 检查
routers/router.go内是否调用了web.Router或web.NSRouter，仅定义结构体不生效 - 如果用注解路由（
// @router / [get]），需确保web.BConfig.WebConfig.AutoRender = false且开启注解扫描：web.AddToPrefix("github.com/beego/beego/v2/server/web", "github.com/beego/beego/v2/core/logs")不要漏掉 - 启动时加
-d参数查看日志：bee run -d，能看到实际注册了哪些路由路径
MySQL 驱动和 ORM 初始化顺序错误
数据库连不上、orm.RunSyncdb panic、或查询返回空 struct，90% 是因为驱动注册和 ORM 初始化顺序颠倒，或者没在 init() 阶段完成。
- 必须先导入 MySQL 驱动：
_ "github.com/go-sql-driver/mysql"（下划线导入，不能省） - 再在
models/init.go或main.go的init()函数里注册 ORM：orm.RegisterDriver("mysql", orm.DRMySQL)+orm.RegisterDataBase("default", "mysql", "root:pass@tcp(127.0.0.1:3306)/mydb?charset=utf8mb4") -
orm.RunSyncdb必须在web.Run()之前调用，否则模型还没加载进 ORM 注册表 - 连接字符串中的
parseTime=true和loc=Asia%2FShanghai要显式加上，否则time.Time字段解析失败
Beego v2 的模块化拆分让每个组件更可控，但也意味着你不能再靠“一个 import 全搞定”。路由、ORM、日志、配置——每个都得独立初始化、显式注册、按顺序执行。漏掉任意一环，应用就静默失败，而不是抛出清晰错误。
