17370845950

Go modules是官方强制的依赖管理机制，go.mod和go.sum必须由命令生成并提交，replace仅限当前模块生效，CI需校验tidy一致性以防止构建漂移。

Go modules 是唯一可行的现代包管理方案

Go 1.11 引入 modules 后，vendor 目录和 GO111MODULE=off 模式已不适用于协作开发。团队若仍在用 dep、glide 或手动 git submodule，会在 go build 行为、CI 一致性、CVE 修复响应上持续出问题。Modules 不是“可选优化”，而是 Go 官方锁定的依赖契约机制。

go.mod 必须提交且禁止手写

go.mod 是机器生成的声明文件，不是配置文件。团队中任何成员执行 go get、go mod tidy 或升级依赖后，都必须提交更新后的 go.mod 和 go.sum。常见错误包括：

• 忽略 go.sum 提交 → CI 构建时校验失败，报错 checksum mismatch
• 手动编辑 go.mod 中的 require 版本号（如改成 v1.2.3）→ 下次 go mod tidy 会覆盖，或引发 indirect 依赖混乱
• 在 go.mod 中保留注释或空行 → go mod 命令会自动格式化并删除，造成无意义 diff

正确做法：所有变更通过命令驱动：

go get github.com/sirupsen/logrus@v1.9.3
go mod tidy
git add go.mod go.sum

统一使用 replace 做私有模块或临时 patch

团队内部多个服务共用一个私有工具库（如 gitlab.example.com/go/utils），或需临时修复上游 bug 时，不能靠改本地 $GOPATH 或软链接。必须在根 go.mod 中声明 replace：

replace gitlab.example.com/go/utils => ./internal/utils
replace github.com/gorilla/mux => github.com/gorilla/mux v1.8.0

注意：

• replace 只在当前 module 生效，不会传递给依赖你的下游 module
• 路径替换（=> ./xxx）必须是相对路径，且目标目录含有效 go.mod
• 上线前必须移除临时 replace，否则生产环境无法拉取真实版本

CI 流程中强制校验 go mod 状态

仅靠开发者自觉提交 go.mod 不可靠。CI 脚本必须包含两步校验：

• 运行 go mod tidy -v 并检查退出码；若输出新增/删除行，说明本地未同步
• 执行 git status --porcelain go.mod go.sum，非空则立即失败

示例 GitHub Actions 片段：

- name: Check go.mod consistency
  run: |
    go mod tidy -v
    if [ -n "$(git status --porcelain go.mod go.sum)" ]; then
      echo "go.mod or go.sum is not up to date"
      exit 1
    fi

这点容易被忽略：很多团队只做 go build，却放过了依赖声明漂移——它不会立刻报错，但会让不同人构建出行为不一致的二进制。