Beego v2 是当前唯一能正常安装并用于新项目的版本，v1 已停更且与 Go 模块系统冲突；安装需执行 go get -u github.com/beego/beego/v2 和 go get -u github.com/beego/bee/v2，路径必须含 /v2、命令必带 -u、$GOPATH/bin 需加入 PATH，导入路径为 github.com/beego/beego/v2/server/web，启动用 web.Run() 且控制器继承 web.Controller。
Beego v2 是当前唯一能跑起来的新项目版本，v1 不仅停更，还和 Go 模块系统硬冲突——所有“安装失败”“bee 命令找不到”“undefined: beego.Run”问题，90% 都卡在环境配置或路径写错上，不是框架难，是步骤漏了一环。
go get 必须带 -u 且指定 /v2 路径
不加 -u 会拉取本地缓存的过期版本（尤其 Windows 下 GOPROXY 失效时，常卡在 v1.12.x）；用旧路径如 github.com/astaxie/beego 直接报错。只认这两条命令，顺序不能反：
go get -u github.com/beego/beego/v2go get -u github.com/beego/bee/v2
如果提示 no required module provides package，说明当前目录没初始化模块：先 go mod init myapp，再重试。
$GOPATH/bin 必须进 $PATH 才能识别 bee
bee 二进制默认生成在 $GOPATH/bin，但终端找不到命令，几乎全是 PATH 没配对。验证三步：
- 运行
go env GOPATH看输出路径（比如/Users/xxx/go） - 确认该路径下存在
bin/bee（macOS/Linux）或bin/bee.exe（Windows） - 把完整路径（如
/Users/xxx/go/bin）加入PATH，新开终端后bee version应输出类似v2.1.0
Mac/Linux 用户别手抖把 bee 复制到 $GOROOT/bin——那是 Go 自身工具的地盘，放错会导致后续 go 命令异常。
import 和启动函数必须严格匹配 v2 规范
v2 拆了包结构，v1 写法一运行就炸，不会“兼容性降级”。常见错误现象：undefined: beego.Run 或 cannot use type beego.Controller as type web.Controller。必须改这三处：
- 导入路径：从
import "github.com/astaxie/beego"改为import "github.com/beego/beego/v2/server/web" - 启动函数：从
beego.Run()改为web.Run() - 控制器继承：从
type MainController struct { beego.Controller }改为type MainController struct { web.Controller }
这些改不动，go build 或 bee run 直接报错，不会“勉强运行”。
go mod tidy 是创建项目后第一件事
bee new demo 后立刻 bee run 报 missing go.sum entry？这不是 Beego 缺依赖，是 Go Modules 的校验机制在起作用。解决只需一步：
- 进入项目根目录（含
main.go和go.mod），执行go mod tidy
如果仍失败，大概率是代理没生效：再执行一次 go env -w GOPROXY=https://goproxy.cn,direct；极少数情况是本地模块缓存损坏，可 go clean -modcache 清空后再试。
新手最容易忽略的是：v2 的导入路径、启动函数、控制器继承这三处必须同步改，漏一个就编译不过；还有就是 bee 命令找不到时，90% 不是没装，而是 $GOPATH/bin 没进 PATH——别在 GOPATH 里找 bee，先看 echo $PATH 里有没有它。
