Go modules 是 Go 1.11 引入的依赖管理机制，默认仅在 GOPATH 外启用；需确保项目不在 $GOPATH/src 下，执行 go mod init 初始化，再用 go mod tidy 或 go build 自动下载并记录依赖，replace 用于临时替换依赖但不可提交至生产环境。
Go modules 是什么，什么时候该启用
Go 1.11 起引入 go mod，但默认仅在 GOPATH 外才自动启用。如果你的项目路径在 $GOPATH/src 下，即使用了 Go 1.16+，go build 仍可能走旧的 GOPATH 模式，导致 go.mod 被忽略。判断是否生效最直接的方式是运行：go list -m
，若报错 no modules found，说明当前未启用 module 模式。
启用方式很简单：确保项目目录不在 $GOPATH/src 内（比如放在 ~/projects/myapp），然后执行：go mod init myapp
。模块名不必是域名，但建议用可识别的唯一标识（如 github.com/you/project），否则后续引用私有包或发布到私有代理时容易出问题。
go mod init 后依赖不会自动下载，要显式触发
go mod init 只生成空的 go.mod 文件，不会分析现有代码中的 import 并拉取依赖。常见错误是 init 后直接 go run main.go 报 cannot find package —— 这是因为 import 的第三方包还没下载，且 go.mod 里没记录。
正确做法是：
- 先确保所有
import 路径合法（例如 import "github.com/spf13/cobra"）
- 运行
go build 或 go run，Go 会自动解析 import、下载对应版本，并写入 go.mod 和 go.sum
- 也可手动补全：运行
go mod tidy，它会删掉未使用的依赖、加上缺失的依赖，并更新 go.sum
注意：go mod tidy 不会升级已有依赖的主版本（如从 v1.2.0 升到 v2.0.0），除非你显式 go get github.com/xxx@v2.0.0。
替换私有仓库或本地模块要用 replace，不是修改 import 路径
当你在开发中想临时用本地修改的依赖（比如调试 github.com/you/lib），不能靠改代码里的 import 为 ./local-lib —— Go 不允许相对路径 import 非主模块。
正确方式是在 go.mod 末尾加：replace github.com/you/lib => ../lib
或指向 Git 分支：replace github.com/you/lib => github.com/you/lib v1.3.0-dev
注意：
-
replace 只在当前模块生效，子模块不会继承
- 如果被 replace 的包本身有依赖，那些依赖不会被自动重定向，可能引发版本冲突
- 上线前务必删掉
replace 行，否则 CI 构建会失败（因为 CI 环境没有你的本地路径）
go.sum 不是锁文件，但校验逻辑比想象中严格
go.sum 记录每个依赖模块的 checksum，用于防止依赖被篡改。但它不锁定子依赖的版本（那是 go.mod 的事）。一个常被忽略的细节是：只要 go.mod 中某个依赖的版本号不变，哪怕远程 tag 被强制推送覆盖（比如有人 git push --force 了 v1.2.0），下次 go build 仍会校验失败并报错：checksum mismatch for github.com/xxx@v1.2.0
这是因为 go.sum 存的是首次下载时的 hash，而 Go 不允许跳过校验。解决方法只有两个：
- 手动删掉
go.sum 对应行，再 go mod download（不推荐）
- 让上游重新发新版本（如
v1.2.1），然后 go get github.com/xxx@v1.2.1
所以别把 go.sum 当成可随意提交/忽略的文件——它和 go.mod 一样，必须随代码一起提交。
go mod init 只生成空的 go.mod 文件，不会分析现有代码中的 import 并拉取依赖。常见错误是 init 后直接 go run main.go 报 cannot find package —— 这是因为 import 的第三方包还没下载，且 go.mod 里没记录。
正确做法是：
- 先确保所有
import路径合法（例如import "github.com/spf13/cobra"） - 运行
go build或go run，Go 会自动解析 import、下载对应版本，并写入go.mod和go.sum - 也可手动补全：运行
go mod tidy，它会删掉未使用的依赖、加上缺失的依赖，并更新go.sum
go mod tidy 不会升级已有依赖的主版本（如从 v1.2.0 升到 v2.0.0），除非你显式 go get github.com/xxx@v2.0.0。
替换私有仓库或本地模块要用 replace，不是修改 import 路径
当你在开发中想临时用本地修改的依赖（比如调试 github.com/you/lib），不能靠改代码里的 import 为 ./local-lib —— Go 不允许相对路径 import 非主模块。
正确方式是在 go.mod 末尾加：replace github.com/you/lib => ../lib
或指向 Git 分支：replace github.com/you/lib => github.com/you/lib v1.3.0-dev
注意：
-
replace 只在当前模块生效，子模块不会继承
- 如果被 replace 的包本身有依赖，那些依赖不会被自动重定向，可能引发版本冲突
- 上线前务必删掉
replace 行，否则 CI 构建会失败（因为 CI 环境没有你的本地路径）
go.sum 不是锁文件，但校验逻辑比想象中严格
go.sum 记录每个依赖模块的 checksum，用于防止依赖被篡改。但它不锁定子依赖的版本（那是 go.mod 的事）。一个常被忽略的细节是：只要 go.mod 中某个依赖的版本号不变，哪怕远程 tag 被强制推送覆盖（比如有人 git push --force 了 v1.2.0），下次 go build 仍会校验失败并报错：checksum mismatch for github.com/xxx@v1.2.0
这是因为 go.sum 存的是首次下载时的 hash，而 Go 不允许跳过校验。解决方法只有两个：
- 手动删掉
go.sum 对应行，再 go mod download（不推荐）
- 让上游重新发新版本（如
v1.2.1），然后 go get github.com/xxx@v1.2.1
所以别把 go.sum 当成可随意提交/忽略的文件——它和 go.mod 一样，必须随代码一起提交。
replace 只在当前模块生效，子模块不会继承replace 行，否则 CI 构建会失败（因为 CI 环境没有你的本地路径）go.sum 记录每个依赖模块的 checksum，用于防止依赖被篡改。但它不锁定子依赖的版本（那是 go.mod 的事）。一个常被忽略的细节是：只要 go.mod 中某个依赖的版本号不变，哪怕远程 tag 被强制推送覆盖（比如有人 git push --force 了 v1.2.0），下次 go build 仍会校验失败并报错：checksum mismatch for github.com/xxx@v1.2.0这是因为
go.sum 存的是首次下载时的 hash，而 Go 不允许跳过校验。解决方法只有两个：
- 手动删掉
go.sum对应行，再go mod download（不推荐） - 让上游重新发新版本（如
v1.2.1），然后go get github.com/xxx@v1.2.1
go.sum 当成可随意提交/忽略的文件——它和 go.mod 一样，必须随代码一起提交。
