Go 导入 internal 包为什么提示不允许使用

项目拆成多个 Go module 后，最容易让人困惑的报错之一就是 use of internal package ... not allowed。它通常不是依赖没下载下来，也不是 GOPROXY 配错，而是导入方不在目标 internal 目录允许的路径树里。判断时只抓住一句话：internal 上方的路径前缀，必须是导入方 import path 的前缀。

要修复这个错误，先从报错路径找到 internal 的共同祖先，再对照导入方的 module 路径。仓库内共享就把调用方放在共同祖先下面；如果 API 要给其他模块使用，就不要把它放在 internal。

先看 internal 规则到底比较哪一段路径

假设目录和模块如下：

shop/
  go.mod                 // module example.com/acme/shop
  internal/cache/
    cache.go
  cmd/api/
    main.go

cache 的完整导入路径是 example.com/acme/shop/internal/cache，internal 上方的共同祖先是 example.com/acme/shop。因此 example.com/acme/shop/cmd/api 可以导入它；如果另一个模块 example.com/report 写同样的 import，就会被拒绝。关键比较的是 import path，不是两个目录在本机上是否恰好相邻。

还有两个容易漏掉的细节：

• 代码位于 internal 目录本身或它的子目录，都受同一条规则约束。
• 路径中出现多层 internal 时，越靠后的那一层会形成更窄的边界，不能只检查第一层。

对照 go.mod 判断调用方是否属于同一模块路径

“我明明在同一个仓库里”并不能直接证明导入合法。Go 模块边界由各自的 go.mod 决定，仓库里的子目录如果有另一个 go.mod，就可能已经是另一个模块。先分别在被导入包和报错调用方所在目录查看模块路径：

# 在调用方目录执行，确认当前模块路径
go list -m -f '{{.Path}}'

# 输出当前包的 import path 和磁盘目录
go list -f '{{.ImportPath}} => {{.Dir}}' .

如果结果是 example.com/acme/shop，调用方路径又以这个前缀开头，通常符合规则。若结果变成 example.com/acme/report，即使两个项目都在一个 Git 仓库里，也不属于 shop/internal 的允许树。

replace example.com/acme/shop => ../shop 只告诉 Go 去本地目录读取模块源码，模块身份仍然是 example.com/acme/shop。它能解决本地开发时的版本联调，不能把外部调用方伪装成内部调用方。类似地，清理模块缓存、切换代理或重新执行 go mod tidy，也不会改变可见性判断。

用 go list 定位真正触发错误的调用方

报错常常出现在一长串依赖链的末尾，真正的调用方可能是测试包、工具命令或工作区中的另一个 module。可以先让 Go 展开当前模块的包路径：

# 列出当前模块下的包，观察调用方是否落在共同祖先下
go list ./...

# 查看依赖图中的模块身份，不把本地目录误当成 import path
go list -m all

如果是测试触发，检查测试文件所在包的 import path；package xxx_test 仍然位于这个目录对应的包路径上，并不会自动获得其他模块的权限。若使用 go.work，工作区只是把多个 module 放在一次构建中，不能把它们合并成一个 import path 前缀。

按包的公开性选择修复方案

定位完成后不要急着删掉 internal。它的价值正是告诉外部使用者：这里是仓库实现细节，API 可以随内部重构而变化。可以按下面的约束选方案：

• 只给本仓库的命令或服务使用：保留 internal，把调用方移动到它上方共同祖先的目录树中，例如让 cmd/api 和 cmd/worker 都位于 example.com/acme/shop 下。
• 多个仓库都要依赖稳定能力：将经过设计和兼容承诺的 API 移到顶层公开包或 pkg/，并使用新的公开 import path。
• 只是仓库目录拆分不合理：把 internal 提升到多个命令的共同祖先，而不是为每个调用方复制一份实现。

例如，下面这种布局适合多个命令共享内部代码：

repo/
  go.mod                 // module example.com/acme/shop
  internal/auth/
  cmd/api/
  cmd/worker/

如果 auth 要被 example.com/acme/report 使用，就应重新设计公开包的接口、错误和兼容策略，而不是通过复制目录、改代理或给 import 加别名“绕过”限制。改完目录后同步修改 import，并让旧路径尽快停止出现在代码和文档中。

用 go test 和 go list 反向确认修复

修复的验收重点不是“缓存被清空”，而是调用方的 import path 已经落在正确边界内。先在模块根目录运行：

# 编译并测试当前模块中的所有包
go test ./...

# 再次列出包路径，确认移动后的调用方位置
go list ./...

若仍报错，按“报错中的被导入路径 → internal 上方前缀 → 调用方 module 路径”重新走一遍。对于确实跨模块的调用，不要继续尝试 GOPROXY、go clean -modcache 或 replace；这时应回到公开包设计或调整模块共同祖先。

常见问题

internal 包是不是不能被任何项目导入？

不是。它可以被同一允许路径树中的包导入，限制的是边界外的调用方。

把代码复制到 vendor 目录能解决吗？

不应把复制当作修复。这样会产生两份实现和升级分叉；先确认模块布局，公开复用则设计公开包。

go.work 能不能让两个模块共享 internal？

不能。go.work 方便本地联合开发，但每个 module 仍保留自己的 import path 和 internal 边界。

为什么同一个仓库里的子项目也会被拒绝？

最常见原因是子项目有独立的 go.mod，它已经成为另一个模块；仓库归属和模块路径不是一回事。

把 internal 当作“按 import path 生效的目录访问边界”，这个报错就不再神秘：先判定允许树，再决定保留内部实现还是公开接口，最后用包列表和测试确认结构已经一致。