Go internal 包在目录外导入失败是怎样的规则

Go 项目里常见的一条报错是 use of internal package ... not allowed。它通常不是包名写错，也不是 go.mod 少了一个依赖，而是调用方站在了 internal 目录允许范围之外。判断规则很具体：找到 import 路径中的 internal，取它前面的父目录；只有位于这个父目录及其子目录中的代码，才能导入该内部包。

例如 example.com/shop/internal/auth 的父目录是 example.com/shop。example.com/shop/cmd/api 可以导入，example.com/worker 和任意外部模块都不可以；即使它们使用了相同的 Go 版本，也不会改变这个边界。

先看 internal 的父目录，而不是先改 go.mod

假设仓库结构如下：

shop/
  go.mod                         // module example.com/shop
  internal/
    auth/
      token.go
  cmd/
    api/
      main.go
worker/
  go.mod                         // module example.com/worker
  main.go

cmd/api/main.go 位于 shop 目录树中，因此可以写 import "example.com/shop/internal/auth"。worker/main.go 是另一个目录树，即使通过 replace 把 example.com/shop 指向本地路径，导入者仍然不在允许范围内。这里先确定“谁在导入”，往往比反复执行 go mod tidy 更快。

目录外导入失败的根因是调用方越过边界

Go 对 internal 的判断可以理解为一个路径前缀规则：若完整 import 路径包含 internal，导入者的路径必须以该 internal 前面的父目录开头。顶层 shop/internal/auth 的允许前缀是 shop；如果是 shop/platform/internal/auth，允许前缀就缩小为 shop/platform。

因此，报错里的关键不是“internal 包坏了”，而是“当前源文件的位置没有资格访问它”。也别把 internal 当成编译器层面的可见性修饰符：它不影响包内部代码如何组织，只限制其他目录树的导入。

用最小示例核对 import 路径和文件位置

下面的结构里，cmd/api 和 internal/auth 属于同一个父目录树；示例只表达静态包关系，不需要先运行代码才能判断边界：

package main

import (
    "fmt"
    "example.com/shop/internal/auth" // 调用方位于 shop 树内，允许导入
)

func main() {
    // 真实项目中这里调用 internal 包暴露的内部能力。
    fmt.Println(auth.Name())
}

如果把同一段代码复制到 example.com/worker，错误会在构建阶段出现。排查清单只有三项：确认 import 的完整路径；定位当前文件属于哪个模块和目录；找到目标路径中 internal 前面的父目录，再比较两者是否处于同一目录树。

需要跨目录复用时，选择正确的修复方案

如果调用方本来就是同一仓库的命令，最小修复通常是把它放回允许的父目录树，例如统一放在 shop/cmd 或 shop/tools 下。如果这个能力确实要给其他项目使用，就不要把外部调用方硬塞进 internal：把稳定、愿意维护的 API 移到公开目录，例如 example.com/shop/auth，内部实现仍可留在 internal 后面。

还可以把可复用能力拆成独立模块，但拆分不是绕过规则的快捷方式。拆分后要重新设计公开 API、版本和依赖边界；仅仅增加 replace、复制目录或修改包名，都不会改变原 internal 的访问范围。

常见问题

同一个 go.mod 下也可能导入失败吗？

可能。决定因素是调用方是否在 internal 父目录树内，而不是只看是否共享一个 go.mod。

把 internal 改成 internal2 能解决吗？

这会失去 Go 的内部包约束，但只是取消保护，不等于设计正确。若确实需要外部复用，应明确移到公开包并整理 API。

replace 指向本地目录为什么仍然失败？

replace 改的是模块解析位置，不会把外部调用方变成 internal 父目录树的子目录。

Go 官方的模块布局建议也把 internal 用作不希望对外承诺的支撑包。遇到导入失败时，先画出“调用方—父目录—internal 包”的三点关系，再决定移动目录还是公开 API，通常几分钟就能定位根因。