replace 必须用绝对路径或 ./ 指向本地模块根目录，禁用纯字符串映射；替换后立即 go mod tidy 并用 go list -m all 验证旧路径是否彻底消失。
go.mod 中 replace 语句怎么写才不会破坏构建
模块路径重命名时，replace 是最常用也最容易出问题的手段。它不是“临时覆盖”，而是直接参与 Go 的模块解析和依赖图构建——写错一点，go build 可能静默跳过某些包，或在 CI 上突然报 cannot find module providing package。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 必须用绝对路径（或
./相对路径）指向本地新模块根目录，不能写成github.com/old/repo => github.com/new/repo—— Go 不支持纯字符串映射 - 如果新模块还没推送到远程，
replace后要立刻运行go mod tidy，否则旧 import 路径仍会从 proxy 拉取旧版本 - 替换后检查
go list -m all | grep oldpath，确保旧路径彻底消失；若还有残留，说明某个间接依赖还在引用它，得逐层查go mod graph
import 语句批量替换的边界情况
编辑器全局替换 import "github.com/old/repo" 看似简单，但 Go 的 import 路径匹配是前缀敏感的。比如把 github.com/old/repo 替成 github.com/new/repo，可能误伤 github.com/old/repo/v2 或 github.com/old/repo-internal。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 用
go fmt -r 'import "github.com/old/repo" -> "github.com/new/repo"' ./...（注意引号和空格），比文本替换更安全 - 替换后立即跑
go build ./...，别等 PR；尤其留意_test.go文件里常有被忽略的 import - 如果模块有
//go:build条件编译，确认所有构建约束下的文件都已更新，否则部分平台会编译失败
go get -u 为什么会回退到旧路径
执行 go get -u 后，某些依赖突然又指向旧路径，常见于：你本地改了 go.mod，但没提交；或者别人在 go.sum 里锁定了旧路径的哈希，而 go get -u 自动拉取最新主干时触发了路径不一致校验。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 迁移期间禁止用
go get -u，改用go get github.com/new/repo@v1.2.3显式指定新路径版本 - 清理
go.sum中所有含旧路径的行（手动删或go mod tidy -v后检查输出），否则go build会因 checksum 不匹配拒绝构建 - 如果项目用了
replace，go get默认忽略它；想让go get尊重 replace，得加-mod=readonly参数，否则它会绕过去拉旧包
私有仓库重命名后的 GOPROXY 和 GONOSUMDB 配置
当新路径属于私有 Git 服务（如自建 GitLab），Go 默认会尝试走 GOPROXY（比如 proxy.golang.org），结果返回 404；同时 go.sum 校验失败，因为私有模块没有公开 checksum。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 在
go env -w中设置：GOPROXY="https://proxy.golang.org,direct"（保留 direct fallback），并确保GONOSUMDB="*.your-company.com"包含新域名 - 如果用
git+ssh协议（如git@company.com:new/repo.git），确认~/.gitconfig里设置了对应 host 的insteadOf规则，否则 Go 无法解析 - CI 环境中，避免只设
GOPRIVATE而漏掉GONOSUMDB—— 前者控制 proxy 行为，后者才允许跳过 sum 检查，两者缺一不可
路径重命名真正难的不是改代码，是让整个生态（本地、CI、依赖方、proxy、sum 校验）同步切换节奏。一个没清理干净的 go.sum 行，或者某台机器上残留的 GOPROXY 缓存，都可能让问题延迟暴露到上线前一刻。
