beego v2 是当前唯一推荐且活跃维护的版本，v1 已停更；安装失败主因是环境配置错误，包括未启用 go111module=on、goproxy 未设国内镜像、$gopath/bin 未加入 $path，以及未使用 /v2 后缀的导入路径和安装命令。
Beego v2 是当前唯一可用的主线版本，v1 已停更；安装失败几乎都卡在环境配置环节，而不是框架本身。
Go 语言环境（最低 Go 1.16+）
Beego v2 依赖较新的 Go 特性（如泛型、模块校验机制），低于 Go 1.16 可能编译失败或运行时 panic。验证方式：
go version
若输出低于 go1.16，需升级。不建议用系统包管理器安装（如 apt/yum 自带的旧版），应从 go.dev/dl 下载二进制包手动安装。
-
GO111MODULE=on必须启用，否则go get会跳过模块解析，拉到错误路径或缓存旧版 -
GOPROXY强烈建议设为国内镜像，例如：go env -w GOPROXY=https://goproxy.cn,direct -
GOPATH不再强制要求，但若使用bee new创建项目，仍需确保$GOPATH/bin在$PATH中，否则bee命令无法执行
bee 命令行工具（v2 版本）
bee 是 Beego 官方 CLI，不是可选插件——项目初始化、热重载（bee run）、路由生成等都依赖它。必须安装 v2 版本，与 Beego v2 对齐：
go install github.com/beego/bee/v2@latest
常见错误：
-
command not found: bee：检查$GOBIN或$GOPATH/bin是否在$PATH中，运行echo $PATH确认 -
bee version显示正常，但bee new myapp报no required module provides package：说明当前目录不在 Go module 路径下，先执行go mod init myapp再试 - Windows 用户注意：
bee.exe默认生成在%GOPATH%\bin，CMD/PowerShell 需重启才能识别新 PATH
网络与代理配置（关键但常被忽略）
Beego v2 的依赖树包含 golang.org/x/... 等包，直连 golang.org 在多数地区超时。仅设置 GOPROXY 不够，还需确保：
-
go env -w GOSUMDB=off（临时调试用）或保持默认sum.golang.org，但必须配合有效GOPROXY，否则go mod tidy卡住 - 若公司内网有防火墙，需确认
goproxy.cn或mirrors.aliyun.com/goproxy可访问；失败时可临时切 direct：go env -w GOPROXY=direct，再手动git clone补依赖 -
go clean -modcache是解决“看似装了却找不到包”的最快手段，尤其在混用 v1/v2 或切换代理后
最易被跳过的细节：所有命令必须用 v2 后缀，go get github.com/beego/beego/v2 和 go install github.com/beego/bee/v2@latest 不能省略 /v2；路径写错一个字符（比如漏掉 v2 或写成 v1），后续所有控制器继承、启动函数都会编译失败。
