go mod init 必须在项目根目录显式指定与代码托管地址完全一致的模块路径（如github.com/yourname/project），否则导致import失败、go get不可用及后续构建错误。
确认项目根目录是否已有 go.mod
历史项目往往没有 go.mod 文件，直接运行 go mod init 会生成默认模块路径（如 module example.com），但这个路径和你实际想发布的模块名不一致，会导致下游无法正确 go get。必须在项目根目录执行：
go mod init github.com/yourname/yourproject其中
github.com/yourname/yourproject 要和代码托管地址完全一致（包括大小写、路径层级）。如果项目将来要发布到私有仓库，这里填的是 VCS 地址的路径部分，不是自定义别名。
处理本地 import 路径硬编码问题
老项目常直接 import 类似 "utils" 或 "./models" 这样的相对路径或短名称，Go 模块要求所有 import 必须是完整模块路径 + 子路径。例如：原 import "utils" 需改为 import "github.com/yourname/yourproject/utils"。注意以下几点：
- 所有
.go文件中的 import 语句都要批量更新，不能漏掉测试文件（*_test.go） - 如果项目内有多个子模块（如
cmd/,internal/,pkg/），它们的 import 路径仍以主模块名为前缀，不要额外加cmd/等前缀 - 使用
go list -f '{{.ImportPath}}' ./...可快速检查当前所有包的解析路径是否统一
解决 go mod tidy 报错依赖找不到
执行 go mod tidy 后常见错误如：cannot find module providing package github.com/xxx/yyy，通常是因为：
- 项目中引用了另一个尚未初始化为 Go 模块的本地仓库（比如公司内部 GitLab 上的私有库），它没
go.mod，也没打 tag —— 此时需先在那个仓库根目录运行go mod init并至少打一个v0.1.0tag - 引用了已归档或迁址的开源库（如旧版
gopkg.in/yaml.v2），要手动替换为当前维护的路径（如gopkg.in/yaml.v3） - 某些 vendor 下的代码仍残留旧 import，
go mod tidy会忽略 vendor 目录，建议先删掉vendor/再执行
go.mod 中应只含真实远程依赖，且 go.sum 文件生成完毕。
验证模块可被外部正确下载
不要只在本机 go build 成功就认为 OK。真正关键的是：别人能否用 go get 拉下来。模拟外部环境测试：
mkdir /tmp/testmod && cd /tmp/testmod<br>GO111MODULE=on go mod init test<br>GO111MODULE=on go get github.com/yourname/yourproject@main如果失败，重点看错误里提到的 import 路径是否拼写错误、对应分支是否存在、是否设置了 GOPRIVATE（私有模块需配置否则走 proxy 会 404）。另外，确保 Git 仓库的
main 分支存在且可读，tag 名必须符合语义化版本格式（v1.2.3，不能是 1.2.3 或 release-1.2）。
最易被忽略的是：模块路径一旦写进 go.mod 并推送到公开仓库，就不能再随意改——下游已 go get 的版本会永久锁定旧路径。改错一次，就得发新 major 版本（v2）并调整 import 路径，成本很高。
