Go模块的import路径必须严格匹配go.mod中module声明的路径，子包是其路径延伸；replace仅用于临时开发且需路径合法；私有模块须配置GOPRIVATE跳过代理校验。
Go mod init 后 import 路径必须匹配模块名
Go 的 import 路径不是文件路径，而是模块路径（module path），它由 go.mod 文件中的 module 声明决定。如果你执行 go mod init example.com/myapp，那所有内部子包的 import 必须以 example.com/myapp/... 开头，哪怕它们物理上在本地 ./pkg/utils 目录下。
常见错误：新建项目后直接用 import "./pkg/utils" 或 import "myapp/pkg/utils" —— 这两种写法都会导致 import path does not begin with hostname 或 no required module provides package。
- 确保
go.mod中的module值是合法域名前缀（如github.com/username/project），即使不发布到公网也推荐这么写 - 子目录包无需额外
go mod init；整个项目共用一个模块，子包只是路径延伸 - 如果模块名改了（比如从
myproject改成github.com/u/p），所有已存在的import语句必须批量更新
跨模块依赖：用 replace 临时指向本地路径
当你有两个独立模块（比如 github.com/u/lib 和 github.com/u/app），而 app 想引用正在开发中的 lib，又不想每次改完都 go mod publish，就得用 replace。
在 app/go.mod 中添加：
replace github.com/u/lib => ../lib
注意：../lib 必须是一个含有效 go.mod 的目录，且其 module 声明必须与 replace 左侧完全一致（包括大小写和斜杠）。
-
replace只在当前模块生效，不会影响下游依赖它的其他项目 - 上线前务必删掉
replace行，否则构建环境找不到../lib - CI 环境中禁止使用相对路径
replace；可用replace github.com/u/lib => git@github.com:u/lib.git v0.1.0-xxx替代
vendor 目录不能解决 import 路径错误
有人以为 go mod vendor 后就能随便改 import 路径，其实不然。vendor 只是把依赖代码复制进来，import 解析仍严格按模块路径进行。如果源码里写的是 import "github.com/sirupsen/logrus"，vendor 里哪怕有 ./vendor/github.com/sirupsen/logrus，你也不能改成 import "vendor/github.com/sirupsen/logrus" —— Go 不认这种写法。
-
vendor是构建隔离手段，不是 import 重定向机制 - 启用 vendor 后，
go build -mod=vendor才会只读取 vendor 内容；默认仍走$GOPATH/pkg/mod - 团队协作中若启用 vendor，建议统一提交
vendor/并禁用GO111MODULE=off
私有模块 import 失败：GOPRIVATE 配置漏了
公司内网 Git（如 gitlab.example.com/group/repo）默认被 Go 当作公共模块处理，会尝试走 proxy.golang.org 或 sum.golang.org 校验，结果报错 verifying github.com/...: checksum mismatch 或直接超时。
解决方法是在 shell 中设置：
go env -w GOPRIVATE=gitlab.example.com/group/*
或者更宽泛地：
go env -w GOPRIVATE=*.example.com
这样 Go 就跳过代理和校验，直连 Git 服务器拉取代码。
- 该配置影响所有模块，不只是当前项目
- 多个域名用逗号分隔，如
GOPRIVATE=gitlab.example.com,bitbucket.internal - 如果用 SSH 克隆私有库，确保
~/.ssh/config正确配置了 Host 别名，否则go get会卡在认证环节
跨模块 import 的核心就三点：模块路径即 import 路径、replace 是临时开发方案而非长期解法、私有域名必须显式加入 GOPRIVATE。最容易被忽略的是 replace 的路径合法性检查——Go 不报错但静默忽略无效 replace，导致你以为引用成功，实际还在用旧版本。
