跨包引用需确保import路径匹配go.mod中定义的模块路径，如module github.com/yourname/project，则必须用github.com/yourname/project/pkg/utils；internal目录用于限制包可见性，仅同模块路径前缀的包可导入；循环引用应通过抽离公共包或接口解耦；升级依赖后需核对go.sum与vendor一致性以防运行时panic。
跨包引用时找不到包名？检查 import 路径是否匹配模块根目录
Go 的 import 路径不是文件路径，而是模块定义的逻辑路径。如果你在 go.mod 里声明了 module github.com/yourname/project，那所有跨包引用都必须以这个前缀开头，比如 github.com/yourname/project/pkg/utils。哪怕你的 utils 文件夹就在当前项目根目录下一层，也不能写成 ./pkg/utils 或 pkg/utils —— Go 会直接报错 cannot find package "pkg/utils"。
常见错误场景：
- 本地开发时用相对路径测试通过，提交后 CI 失败
- 把一个包从
internal移到pkg，但没更新所有import语句 - 模块名含大写字母（如
MyProject），导致 Windows/macOS 下大小写不敏感掩盖问题，Linux 构建失败
想复用内部工具包但又不想暴露给外部？用 internal 目录限制可见性
internal 不是关键字，而是一个约定俗成的目录名，Go 编译器会强制检查：只有和 internal 目录有相同模块路径前缀的包才能导入它。比如 github.com/yourname/app/internal/db 只能被 github.com/yourname/app/... 下的包引用，github.com/other/repo 就算硬写 import 也会编译失败。
注意点：
立即学习“go语言免费学习笔记（深入）”；
-
internal必须是路径中的一级目录名，pkg/internal/utils不受保护 - 不能嵌套多层
internal/internal，第二层起就失效 - 如果模块路径是
.（即未初始化模块），internal机制不生效
多个包循环引用了怎么办？拆出第三包或改用接口解耦
Go 编译器禁止直接的循环 import：A → B → A 会报 import cycle not allowed。它不看函数调用链，只看 import 语句层级。
可行解法：
- 把共用类型或方法抽到新包（如
github.com/yourname/project/domain），让 A 和 B 都只依赖 domain - A 包导出接口（如
type Storer interface { Save() }），B 包实现它，A 通过参数接收该接口，避免 import B - 用回调函数代替结构体字段依赖（例如 A 不持有
*B.Service，而是接受func() error）
别试图用 _ 导入或延迟 init 函数绕过，这只是掩盖问题，且会让依赖关系更难追踪。
升级依赖后编译通过但运行 panic？检查 vendor 和 go.sum 是否一致
即使 go build 成功，如果依赖包的 API 在小版本中变更（比如 v1.2.3 → v1.2.4），而你没跑测试，很可能在运行时才暴露问题，典型如 nil pointer dereference 或 interface conversion: X is not Y。
建议动作：
- 升级前先看目标包的 CHANGELOG 或 GitHub Releases，重点关注
Breaking changes - 执行
go mod graph | grep 'old-package'查哪些包间接依赖它 - 若使用
vendor，确认go mod vendor后vendor/modules.txt和go.sum一致，否则可能 vendor 里是旧版，而go build实际读的是缓存
跨包依赖真正麻烦的从来不是“怎么写 import”，而是“谁在什么时候、以什么方式、依赖了哪个版本的哪一部分”。越早用 go list -f '{{.Deps}}' xxx 看清依赖树，后面踩的坑就越少。
