Go internal 目录在多模块工作区中为何不能跨越

在多模块工作区里，两个目录明明挨着，导入 internal 包却仍然报错，最容易误判的地方是把“同一个 go.work”当成了“同一棵可见性树”。Go 的规则看的是导入路径：internal 之前的父路径决定允许范围，物理目录相邻、同仓库或同一工作区都不能改变它。

先按导入路径画出 internal 的允许树

假设公共模块的路径是 example.com/acme/common，目录如下：

# 目录只是示意，真正参与判断的是 go.mod 声明的导入路径
common/internal/log      # 导入路径：example.com/acme/common/internal/log
common/service            # 导入路径：example.com/acme/common/service
app                       # 导入路径：example.com/acme/app

common/service 可以使用这个内部包，因为它位于 example.com/acme/common 这棵树下；example.com/acme/app 则不可以。判断式可以写成：删除导入路径中的 /internal/log 后，导入方路径是否以 example.com/acme/common 开头。

这里的“开头”要按路径段判断。例如父路径是 example.com/acme/common 时，example.com/acme/commonish 不是合法子树。编译器拒绝导入时，看到的常见信息是 use of internal package ... not allowed，它说明的是路径边界不匹配，不是包没有被工作区找到。

go.work 能联通模块，但不能跨越可见性边界

工作区可以把 common 和 app 同时列入 go.work，让 app 直接使用本地的 common 模块版本。这改变的是模块解析来源，没改变两个模块各自声明的导入路径。

# go.work 位于仓库根目录，只声明参与工作区的模块
go 1.22

use (
    ./common
    ./app
)

如果 common/go.mod 声明 example.com/acme/common，而 app/go.mod 声明 example.com/acme/app，那么 app 仍在 example.com/acme/common 之外。只有把内部包放在更高的共同父路径下，例如 example.com/acme/internal/log，并让两个模块的导入路径都落在 example.com/acme 树中，才可能同时满足规则。

这也是为什么添加 replace example.com/acme/common => ./common 通常只会解决“找不到本地版本”，不会解决“禁止导入”。replace、缓存清理和重新生成 go.work.sum 都不能把兄弟模块变成允许树的子包。

用 go env 和 go list 找到真正的导入方

排查时不要只在文件管理器里看目录。先确认命令使用的模块与工作区，再从导入方所在包的路径判断：

# 查看当前命令所属模块和工作区文件
go env GOMOD GOWORK

# 列出当前模块的导入路径与文件目录，便于对照 internal 父路径
go list -f '{{.ImportPath}} -> {{.Dir}}' ./...

# 查看目标包的依赖关系；错误信息会保留真实的禁止导入原因
go list -deps ./app/...

第一条输出如果是 /dev/null 或空工作区，不代表 internal 规则失效，只说明当前目录没有对应的模块或工作区配置。第二条输出中的 .ImportPath 才是关键证据：把它与目标包中 internal 前的父路径逐段比较。若模块目录只是通过 use 加入工作区，但导入路径仍在父树之外，结论不会改变。

按共享范围选择三种修复方式

如果只是想隐藏实现、又确实要跨模块复用，公开一个小而稳定的接口通常比暴露整棵内部目录更容易维护。包装层可以把日志、配置或协议细节留在原模块内，另一个模块只依赖返回值和错误语义。

常见问题

同一个 Git 仓库里的兄弟模块可以导入 internal 吗？

不一定。仓库归属不是判断条件；只有导入方路径位于 internal 父路径树下才可以。

把两个模块写进 go.work 后为什么还是报错？

因为 go.work 只负责工作区解析。检查两个 go.mod 的 module 行和目标包的完整 import path，通常能直接看到父树不匹配。

用 replace 指向本地目录能绕过限制吗？

不能。它可以改变依赖源码来自哪里，但不会改变导入方的路径身份；应调整包边界或改用公开 API。