根本原因是模块路径与import语句必须严格一致；需同步更新go.mod声明、所有源码import路径、require行及go.sum，并确保子模块发布新路径版本且上游显式升级。
go.mod 路径变更后，为什么 go build 仍报错找不到包？
根本原因是模块路径（module 声明）和所有 import 语句必须严格一致——Go 工具链不认“重命名目录”或“改 remote URL”，只认 go.mod 里写的路径和源码里写的字符串。
- 执行
go mod edit -module github.com/neworg/project更新声明 - 用
find . -name "*.go" -exec sed -i '' 's|github.com/oldorg/project|github.com/neworg/project|g' {} +（macOS）或sed -i 's|github.com/oldorg/project|github.com/neworg/project|g' $(find . -name "*.go")（Linux）批量替换所有import - 运行
go mod tidy清理残留依赖；若提示require github.com/oldorg/project: version "v1.2.0" invalid，说明旧路径还在间接依赖中，需go mod graph | grep oldorg定位并手动删掉对应行
子模块迁移后，主模块构建失败怎么办？
主模块的 go.mod 不会自动感知子模块路径变更。即使子模块已发布新路径版本，主模块仍按原路径拉取，导致 go get 失败或 go build 报 cannot find module。
- 先确认子模块已完成迁移：新仓库有正确
go.mod、打了对应 tag（如v1.2.0）、且 CI 能成功构建 - 在主模块中执行
go get github.com/neworg/submodule@v1.2.0（不是go mod tidy），强制刷新 require 行 - 检查
go.mod中该依赖是否已更新为新路径；若没变，补一句go mod edit -replace github.com/oldorg/submodule=github.com/neworg/submodule@v1.2.0临时绕过，再跑一次go mod tidy -
go.sum里可能残留旧路径哈希，删掉后重新go mod download
多团队协作下，如何避免模块路径冲突？
大型项目常有多个团队维护不同子模块，若各自随意设 module 路径（如都用 example.com/core），会导致 go mod vendor 或 go list -m all 解析混乱，甚至本地构建成功但 CI 失败。
Golang Spf13 Viper
下载
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
- 统一约定路径命名规则，例如
github.com/your-org/{team-name}/{service-name}，禁止使用泛化名如core、utils - 所有子模块初始化时用
go mod init指定完整路径，而非依赖默认推导 - 在 CI 流水线中加校验步骤：
go list -m all | grep -v '^github\.com/your-org/' && exit 1，拦截非法路径引入 - 内部私有模块若走 proxy（如 Athens），需确保其
replace规则与实际路径完全匹配，否则go get会 fallback 到 public repo 并失败
迁移后测试通过但线上 panic，常见原因是什么？
最隐蔽的问题是 replace 未被下游模块继承——你在本地用 replace 绕过路径问题，但其他服务 go get 你模块时，replace 不生效，仍尝试拉旧路径。
立即学习“go语言免费学习笔记（深入）”；
-
replace是当前模块私有指令，不会写入go.mod的require行，也不会传播给依赖方 - 真正解法是：子模块发布正式语义化版本（tag）到新路径，并让所有上游模块显式升级到该版本
- 临时调试可用
go run -mod=mod强制忽略 replace，提前暴露问题 - 上线前务必验证
go mod vendor后的vendor/modules.txt是否含新路径，而非旧路径 + hash
go mod tidy 后突然冒出来。 
