Go import路径必须严格匹配go.mod中module声明，如module github.com/yourname/myapp，则子包导入路径必须为github.com/yourname/myapp/utils，不支持相对路径或截断写法。
Go import 路径必须匹配 go.mod 中的 module 声明
Go 的 import 语句不是文件路径，也不是相对路径，它直接对应模块的逻辑身份。如果你在项目根目录执行了 go mod init github.com/yourname/myapp，那么所有子包的导入路径就必须以 github.com/yourname/myapp 开头。
常见错误是写成 import "myapp/utils" 或 import "./utils" —— 这两种写法都会导致 cannot find module providing package 错误，因为 Go 模块系统根本不会按这种形式去解析或查找。
-
go mod init生成的module行就是整个项目的“命名空间前缀”，不可省略、不可截断 - 即使项目只在本地开发，也建议用带域名的路径（如
example.com/myapp），避免未来迁移或共享时重命名成本 - 路径大小写敏感：若
go.mod写的是github.com/YourName/myapp，但代码里写了github.com/yourname/myapp，Windows/macOS 可能不报错，Linux 下会失败
internal 目录的导入限制不是约定，而是编译器强制规则
internal 不是命名习惯，它是 Go 编译器硬编码的访问控制机制。只要路径中包含 /internal/ 这一级，且该部分处于模块路径的“顶层”，就触发校验。
比如模块路径是 github.com/yourname/myapp，那么 github.com/yourname/myapp/internal/db 是合法的；但 github.com/yourname/myapp/core/internal/db 就不会被识别为 internal 包——因为 internal 不在模块路径的一级子目录中。
立即学习“go语言免费学习笔记（深入）”；
- 只有声明该模块的代码（即同模块下、
internal同级或上级的包）才能导入internal子包 - 外部项目哪怕路径拼对了，也会收到
use of internal package not allowed编译错误 - 这个机制和
go.mod的replace或exclude无关，纯静态检查，不依赖网络或缓存
主版本号变更必须体现在导入路径中（/v2 规则）
当你的模块发布 v2.0.0 时，不能只改 tag，还必须把导入路径升级为 github.com/yourname/myapp/v2。否则 Go 会认为这是同一个模块，MVS（最小版本选择）算法可能拉取错误版本，甚至拒绝构建。
这是因为 Go 把 /v2 当作模块路径的一部分，而非版本后缀。v1 和 v2 在模块系统里是两个完全独立的模块，彼此不兼容、不覆盖、不干扰。
- v2+ 版本必须显式出现在
import路径中，且go.mod的module行也要同步更新 - 如果旧代码仍 import
github.com/yourname/myapp，它只会看到 v1.x 系列；新代码 importgithub.com/yourname/myapp/v2，才可能用上 v2.x - 没有
/v2的 v2 tag 会被 Go 忽略，或降级为伪版本（如v0.0.0-xxx），无法被可靠引用
go.sum 校验失败往往源于路径与模块名不一致
go.sum 文件记录的是每个模块路径 + 版本对应的哈希值。如果某处 import 路径写错（比如少了个 github.com/），Go 会尝试从 GOPROXY 拉取一个不存在的模块，最终要么超时，要么返回 404，接着报 failed to load mod file 或 checksum mismatch。
这类错误表面看是网络或缓存问题，实际根源几乎总是路径拼写与 go.mod 中声明的模块名不一致。
- 检查
go list -m all输出，确认所有依赖路径都以你自己的module前缀开头 - 不要手动编辑
go.sum，它由go mod tidy自动生成和维护 - 若使用
replace本地调试，确保replace行中的目标路径也严格匹配原模块路径（包括大小写和 /vN）
真正容易被忽略的是：模块路径一旦发布并被他人引用，就不能再随意修改。哪怕只是删掉一个 github.com/ 前缀，也会让所有下游构建失败。路径即契约，不是配置项。
