Go 编译器在编译期硬性禁止跨模块引用 internal 包，报错“cannot import internal package”，该限制与 go.mod、环境变量无关，recover 无法捕获，需迁移至 pkg 等显式路径并手动更新所有 import。
internal包被跨仓库引用时编译直接失败
Go 不允许跨模块引用 internal 目录下的包，这不是运行时 panic，而是编译期硬性拒绝。一旦你在 github.com/other/repo 里写了 import "github.com/yourname/project/internal/utils"，go build 会立刻报错：import "github.com/yourname/project/internal/utils": cannot import internal package。
这个限制由 Go 编译器强制执行，不依赖 go.mod 内容或环境变量，也和大小写、路径拼写无关——只要 import 路径含 /internal/ 且前缀不匹配当前模块路径，就拦死。
-
internal必须是路径中的一级目录名，pkg/internal/tool受保护，但pkg/internal/sub/internal/helper中第二层internal无效 - 模块路径为
.（未初始化模块）时，internal机制完全不生效，此时引用看似成功，但一推到 CI 就崩 - Windows/macOS 上因文件系统不区分大小写，可能掩盖
Internal和internal拼写差异，Linux 构建必 fail
误用 recover 捕获 internal 引用错误
recover 对这类编译错误完全无效。它只作用于运行时 panic，而 internal 限制发生在编译阶段，代码根本没机会运行。试图在 init 函数或 main 开头加 defer+recover 来“兜底”，只会白忙一场。
常见误判场景：
立即学习“go语言免费学习笔记（深入）”；
- 本地开发用相对路径
./internal/utils测试通过（因为 go tool 在 module mode 关闭时可能绕过检查），提交后 CI 报错却以为是 panic 可 recover - 把
internal包挪到pkg后忘记更新所有 import，残留的internal引用在构建时报错，误以为是 runtime panic - 在测试中用
go run执行单个文件，没触发模块校验，误以为逻辑没问题
跨仓库复用代码的正确替代方案
想让其他仓库安全使用你的工具代码，必须放弃 internal，改用显式导出路径：
- 把原
internal/utils移到pkg/utils，并确保go.mod的 module 名（如github.com/yourname/project）与 import 路径严格一致 - 若需限制外部使用范围，可在
pkg/utils内部用非导出类型 + 明确文档说明“仅供本组织内项目使用”，而非依赖internal机制 - 对高度敏感逻辑，拆出独立小模块（如
github.com/yourname/shared），单独发版、加版本约束，比藏internal更可控
注意：即使做了上述迁移，旧仓库里所有 import 语句仍需手动更新——Go 不会自动重写 import 路径，IDE 重构支持也有限，漏改一处就导致构建失败。
panic 日志里看不到 internal 相关堆栈
这是最容易被忽略的点：你翻遍 panic 输出的 goroutine 堆栈，永远找不到 internal 相关线索，因为它压根没进 runtime。所有报错信息都来自 go build 或 go test 的编译器输出，格式统一为 cannot import internal package，不带文件行号、不进 recover、不触发 defer。
真正要盯住的是构建日志开头几行——不是 panic 堆栈末尾，而是 go 命令第一行报错。混淆这两类错误，会浪费大量时间在错误的方向上排查。
