因为go get默认只处理远程模块，不支持本地路径；必须用replace指令重定向，要求本地包有匹配module路径的go.mod，且replace路径须为相对于主go.mod的相对路径（如../pkg），执行go mod tidy后生效并显示(replaced)，上线前须移除以确保构建可重现。
为什么 go get 不能直接拉本地路径的包？
因为 go get 默认只处理远程模块（如 GitHub URL），遇到类似 file:///path/to/local/pkg 或相对路径时会报错：invalid version: unknown revision 或 no required module provides package。Go 模块系统不把本地文件系统当作“版本源”，它依赖的是 go.mod 中声明的模块路径与实际代码位置的映射关系。
用 replace 指令重定向模块路径到本地目录
这是最常用、最可靠的方式。前提是本地包本身已初始化为模块（即根目录下有 go.mod，且 module 声明的路径与你主项目 import 语句中写的路径一致）。
- 在主项目的
go.mod文件末尾添加：replace github.com/your-org/your-pkg => ../your-pkg
- 路径必须是相对于当前
go.mod所在目录的相对路径；不能用绝对路径（如/home/user/pkg），否则go build在 CI 或他人机器上会失败 - 执行
go mod tidy后，replace行会被保留，且go list -m all会显示该模块标记为(replaced) - 如果本地包尚未有
go.mod，先在它的根目录运行go mod init github.com/your-org/your-pkg，确保模块路径与 import 路径完全匹配
开发时频繁修改本地包，如何避免反复 go mod tidy？
replace 是静态映射，只要路径存在、模块路径对得上，修改本地包代码后无需任何额外操作——go build 和 go test 会自动使用最新代码。但要注意：
- 如果本地包的
go.mod里声明了依赖，而这些依赖版本与主项目冲突，go build可能报require ...: version ... used for replacement... does not match selected version；此时需在主项目中用replace或exclude协调 - IDE（如 VS Code + Go extension）可能缓存旧导入信息，修改
go.mod后建议重启 Go language server 或执行go mod vendor（若启用 vendor） - 不要在
replace中使用通配符或变量，Go 不支持；也不能用./local这种模糊路径——必须精确到模块根目录
上线前忘记删 replace 会怎样？
不会编译失败，但会导致构建结果不可重现：别人 clone 主项目后，若本地没有对应路径的 ../your-pkg，go build 直接报错。所以：
立即学习“go语言免费学习笔记（深入）”；
- 上线或打 tag 前，务必确认
replace已移除，且目标包已发布到真实 registry（如 GitHub + 正式 tag） - 可以用
go list -m -f '{{if .Replace}}{{.Path}} => {{.Replace.Path}}{{end}}' all快速检查是否还有未清理的replace - CI 流水线中建议加一步校验：
grep -q "replace" go.mod && echo "ERROR: replace still present" && exit 1 || true
真正麻烦的不是怎么加，而是怎么安全地去掉——尤其当多个本地包嵌套替换时，路径错一位就全崩。动手前最好先 git stash 当前 go.mod 变更，验证远程依赖能正常拉取再提交。
