beego项目CI/CD最常卡在四点：bee run不可用于生产构建、app.conf不支持环境变量注入、go test覆盖率被自动生成文件干扰、Docker镜像误含bee工具链；须绕过bee用原生go build、手动注入环境变量、排除非业务包测试、多阶段构建分离工具链与运行时。
Beego 项目在 CI/CD 中最常卡在 bee run 无法用于生产构建、环境配置硬编码、测试覆盖率难采集、以及 Go 模块与 Beego v2 兼容性错位这四点上。直接套用 Gin 或 Fiber 的流水线模板会失败。
beego 项目不能用 bee run 构建生产镜像
bee run 是开发期热重载工具，依赖本地 GOPATH 和源码目录结构，且默认监听 0.0.0.0:8080 并开启调试模式（runmode = dev），CI 环境中既无源码变更监听能力，又会暴露调试接口，根本不可用。
正确做法是绕过 bee CLI，直接用原生 Go 命令构建：
- 确保项目根目录有
main.go（Beego v2 推荐结构：入口文件显式调用beego.Run()） - 构建命令必须指定
-ldflags="-s -w"减小二进制体积 - 禁用 CGO（
CGO_ENABLED=0）以支持 Alpine 镜像静态链接 - 示例构建命令：
CGO_ENABLED=0 go build -ldflags="-s -w" -o mindoc ./main.go
Beego v2 的 app.conf 必须支持环境变量注入
Beego 默认读取 conf/app.conf，但该文件不原生支持环境变量展开（如 ${DB_HOST}）。若直接写死数据库地址，多环境部署只能靠替换文件，CI 流水线极易出错。
解决方案是改用 Beego v2 的 beego.AppConfig + os.Getenv 手动覆盖：
- 在
main.go初始化后插入：beego.AppConfig.Set("db::host", os.Getenv("DB_HOST")) - 或统一在
conf/app.conf中使用占位符（如db_host = "PLACEHOLDER"），启动前用sed -i "s/PLACEHOLDER/$DB_HOST/g" conf/app.conf - 更稳妥的方式：完全弃用
app.conf，改用beego.LoadAppConfig("ini", "conf/app.prod.ini")加载不同环境配置文件，由 CI 根据GITHUB_ENV或CI_ENV变量选择加载路径
Go test 覆盖率统计需排除 Beego 自动生成文件
Beego v2 的 bee generate 会产出 routers/router.go、models/model.go 等文件，这些代码无业务逻辑，但计入 go test -cover 统计，拉高虚假覆盖率，掩盖真实缺陷。
执行测试时应显式排除：
- 使用
go list ./... | grep -v "/routers\|/models\|/controllers/api"动态生成待测包列表 - 或在
go.mod同级新建.coverignore，内容为：routers/* models/* controllers/api/*，再配合自定义脚本过滤 - GitHub Actions 中推荐写成：
go test -coverprofile=coverage.out -covermode=count $(go list ./... | grep -vE "(routers|models|controllers/api)")
Docker 多阶段构建必须区分 bee 工具链与运行时
很多团队把 bee 安装进最终镜像，导致镜像臃肿（bee 依赖大量 dev 工具）、权限失控（root 用户运行 bee）、甚至引入安全漏洞（bee 本身非生产组件）。
正确分层方式：
- 构建阶段：用
golang:1.22-alpine安装bee（仅用于生成代码），再执行go build - 运行阶段：用
scratch或gcr.io/distroless/static-debian12，只 COPY 编译好的二进制和conf/、static/、views/ - 关键检查点：
docker history your-mindoc-image中不应出现bee、git、gcc等关键词
Beego 的 CI/CD 不是“把 Go 流水线复制一遍再换框架名”，它的陷阱藏在配置加载时机、自动生成代码归属、以及 bee 工具链的生命周期管理里——漏掉任一环，上线后就可能连 404 路由都注册不上。
