go.mod 中的 go 指令是行为契约而非版本标签，承诺代码符合指定 Go 版本的语言规范与工具链语义；从 Go 1.21 起强制校验，非标准导入路径（如 vendor 内部路径）会导致 import 解析失败，且 vendor 不改变合法 import 路径；replace 是唯一安全的本地模块映射机制，需配合标准 import 路径使用。
go.mod 中的 go 指令不是版本标签，而是行为契约
你在 go.mod 里写的 go 1.22，不是告诉别人“我用的是 1.22”，而是承诺“本模块所有代码都基于 Go 1.22 的语言规范、工具链行为和标准库语义编写”。从 Go 1.21 开始，这个指令变成强制校验项：如果用 Go 1.20 构建，会直接报错 go version 1.22 requires go version 1.22 or later，不再尝试编译。
不标准导入路径（比如 myproj/vendor/src/github.com/sirupsen/logrus）本身不触发该检查，但它会让整个模块脱离 Go Modules 的语义约束——因为这种路径根本不会被 go list 或 go build 正确解析，工具链甚至不会走到校验 go 指令那一步，而是提前在 import 解析阶段失败。
- 错误现象：编译报
import "myproj/vendor/src/..." not found in any module，或更隐蔽地出现类型不兼容（如cannot use nsq.HandlerFunc(...) as nsq.Handler） - 根本原因：Go 不识别 vendor 内部路径作为合法 import 路径；它只认模块根目录下的相对路径（如
myproj/utils）或标准远程路径（如github.com/sirupsen/logrus） - 兼容性影响：一旦用了非标路径，模块就无法被其他项目通过
go get正常引用，也丧失了go mod tidy和go list -m all的版本追溯能力
vendor 目录 ≠ 导入路径，它只是缓存副本
go mod vendor 只是把当前模块依赖的代码复制到 ./vendor 下，供离线构建使用。它**完全不改变 import 语句的写法**。你仍然必须写 import "github.com/sirupsen/logrus"，而不是 import "vendor/github.com/sirupsen/logrus" —— 后者在任何 Go 版本下都会报错。
有人误以为“既然 vendor 里有代码，那我改 import 路径就能绕过网络拉取”，这是对 Go 包模型的根本误解。Go 的类型系统严格绑定 import 路径，vendor/ 下的代码只有在源码中使用标准路径导入时，才会被工具链关联为同一包。
立即学习“go语言免费学习笔记（深入）”；
- 典型错误：手动把
import "github.com/sirupsen/logrus"改成import "./vendor/github.com/sirupsen/logrus"→ 编译失败，Go 不支持点号开头的本地路径导入 - 更隐蔽的问题：两个模块各自
go mod vendor后，都改写了 import 路径指向自己 vendor 子目录 → 类型不兼容，跨模块传参崩溃 - 向前兼容风险：这类代码在 Go 1.20 可能侥幸通过（因 import 解析松散），但在 Go 1.21+ 会被更早、更明确地拒绝
replace 是唯一安全的本地路径映射机制
当你需要在主模块中引用尚未发布的本地子模块（比如 ../lib），正确做法是在主模块的 go.mod 中用 replace，而不是修改 import 语句。
replace github.com/myorg/lib => ../lib 这行声明的意思是：“当本模块或其依赖试图导入 github.com/myorg/lib 时，请实际加载 ../lib 目录下的代码”。关键在于：代码里仍写标准路径 import "github.com/myorg/lib"，路径不变，语义不变。
- 前提条件：
../lib必须是一个合法 Go 模块（含go.mod），且其module声明必须与replace左侧完全一致 - CI/CD 注意：
replace中的相对路径（如../lib）在 CI 环境中通常不可用，应替换为 git commit hash 引用，例如replace github.com/myorg/lib => git@github.com:myorg/lib.git v0.1.0-20260804123456-abcdef123456 - 发布前必须删除
replace行，否则下游用户go get时会因找不到../lib而失败
向前兼容真正断裂点：类型系统不认“看起来一样”的包
Go 的向前兼容性保障，建立在“相同 import 路径 = 相同包身份”这一铁律上。只要路径不同，哪怕内容一字不差、Go 版本完全一致，它们就是两个独立类型。
这意味着：如果你曾用非标路径（如 myproj/internal/nsq）替代 github.com/bitly/go-nsq，然后在某次升级中又切回标准路径，所有之前用非标路径定义的变量、函数签名、接口实现都会立即失效——编译器不会警告“你改了路径”，只会报一堆 cannot use ... as ... 错误。
这种断裂不是 Go 版本升级导致的，而是路径污染引发的静态类型系统硬性拒绝。它比语法变更更难调试，因为错误位置往往远离 import 语句本身，出现在函数调用、结构体赋值、接口实现等地方。
