internal包跨目录无法导入怎么办

Go 项目遇到 use of internal package not allowed 时，通常不是 go.mod 没下载依赖，而是导入方不在 internal 目录规定的父目录树中。修复的关键不是给 import 路径换个写法，而是让调用方回到允许的目录范围，或重新设计这个包的可见性。

判断规则很简单：对于 example.com/acme/app/internal/config，internal 前面的父路径是 example.com/acme/app。只有该父路径下的包才能导入它；example.com/acme/other 或另一个模块，即使在同一个工作区，也不能直接导入。

官方参考：https://pkg.go.dev/cmd/go

先从 import path 找到允许范围

假设模块布局如下，config 不是整个模块都能使用的公共包：

example.com/acme/
├── go.mod
├── app/
│   ├── cmd/server/main.go
│   └── internal/config/config.go
└── tools/check/main.go

app/cmd/server 位于 example.com/acme/app 下面，因此可以导入 example.com/acme/app/internal/config。tools/check 虽然也属于同一个模块，却在 app 的兄弟目录下，导入就会被 Go 命令拒绝。这里的“跨目录”不是相邻目录不能互相引用，而是跨过了 internal 的封闭父树。

用最小示例区分合法和非法导入

调用方只需要使用完整模块路径导入，不能通过相对路径或别名绕过限制：

package main

import (
    "fmt"

    "example.com/acme/app/internal/config"
)

func main() {
    // 该文件位于 app 的目录树内，因此导入 app/internal/config 是合法的。
    fmt.Println(config.Name())
}

如果把同一段代码放到 example.com/acme/tools/check，常见错误会变成：

use of internal package example.com/acme/app/internal/config not allowed

此时先在报错目录执行下面的命令，确认 Go 看到的模块根和导入路径。命令不会改变依赖，只用于定位：

# 显示当前文件夹属于哪个主模块，避免在错误目录排查。
go env GOMOD

# 展开目标包的实际导入路径和目录位置。
go list -json example.com/acme/app/internal/config

# 读取当前模块声明，核对 module 路径是否与 import 前缀一致。
go list -m

三种修复方式，按复用范围选择

例如 app/internal/config 同时被 app/cmd/server 和 tools/check 需要时，可以把它整理为 example.com/acme/internal/config，让两个目录都落在共同父树下。但如果这个包只承载 app 的私有实现，不要为了消除一次报错就把它公开。

工作区和 replace 不能绕过 internal 规则

go.work 可以把多个模块放到同一工作区，replace 可以改变模块来源，但它们不会取消 internal 的目录限制。判断权限时仍然要看导入方的实际 import path 是否位于目标包父树中。若调用方来自另一个模块，最稳妥的做法是提供公开包，或把共享的内部实现移动到两个模块都能合法访问的独立模块。

还要留意模块路径和磁盘目录是否对应。一个目录看起来在 app 下，如果其中另有 go.mod，它可能已经成为独立模块；这时“磁盘上相邻”不能替代 import path 的父树关系。

相关问题

同一个 go.mod 里为什么也会报错？

因为规则检查的是 internal 前面的父路径，不是只检查是否共享一个模块根。模块内的兄弟目录仍可能位于允许范围之外。

改成相对路径能绕过吗？

不能。模块模式下应使用完整 import path，Go 仍会按解析后的包路径检查 internal 边界。

应该直接删除 internal 吗？

只有当包确实需要被外部模块复用时才这样做。内部实现优先调整到共同父目录，删除限制会带来长期 API 兼容责任。

所以，排查这个报错时先画出 internal 前面的父目录，再核对调用方的 import path。路径在边界内就修正模块布局或工作目录；路径确实在边界外，就在封装与公开复用之间做一次明确取舍。