Go test 为什么找不到内部包

我在把公共逻辑拆到 internal 目录后，第一次遇到的不是编译器语法错误，而是 go test 突然提示内部包不可导入，或者看起来像“找不到包”。这类问题通常不在测试命令，而在测试文件所在的导入树越过了 internal 的边界。

结论先说：internal 包只能被它所在目录的直接父目录树中的代码导入。测试代码如果放在这个树外，即使它属于同一个仓库，go test 也会拒绝导入；把测试放回允许的目录，或改为通过公开 API 测试，才是正确修复。

官方资料：https://go.dev/doc/go1.4#internalpackages

先看报错：到底是“路径不对”还是“越过边界”

我会先把错误分成两类。若报错包含 use of internal package ... not allowed，说明 Go 已经解析到了这个包，真正的问题是导入者不在允许的父目录树中。若报错是 cannot find package、no required module provides package 或导入路径拼写错误，则要先检查 module 路径和目录名，不能把所有问题都归咎于 internal。

example.com/acme/payments/
├── go.mod
├── internal/
│   └── money/
│       └── money.go
├── service/
│   └── invoice_test.go
└── tools/
    └── report_test.go

service/invoice_test.go  -> example.com/acme/payments/internal/money  合法
tools/report_test.go     -> example.com/acme/payments/internal/money  通常也合法
../external-check/test   -> example.com/acme/payments/internal/money  不合法

这里的关键不是“有没有同一个 Git 仓库”，而是导入者的包目录是否落在 internal 直接父目录 example.com/acme/payments 所代表的树中。测试放在仓库旁边的独立目录、另一个 module，或者被工作区解析成外部包时，都可能触发边界错误。

internal 的边界是由父目录决定的

假设内部包的完整路径是 example.com/acme/payments/internal/money，Go 会把 example.com/acme/payments 视为允许导入的根。service、tools 和它们的子目录都在根下面；example.com/acme/other、临时测试目录或另一个仓库则不在范围内。

这个规则也解释了一个容易误会的情况：外部测试包写成 package service_test 并不会自动离开目录边界。只要测试文件仍在 service 目录中，它的导入者路径仍然属于允许树；真正改变结果的是文件所在目录、module 根和最终解析出的导入路径。

最稳的修复：让测试与被测代码处在同一棵树

如果测试确实需要直接使用 internal/money，可以把测试放在 module 根目录下面的业务包中。下面的例子把测试放在 service 包里，使用外部测试包名保持黑盒测试习惯，但导入者仍然在允许树内。

package service_test

import (
	"testing"

	"example.com/acme/payments/internal/money"
)

func TestInvoiceAmount(t *testing.T) {
	// 测试只依赖内部包暴露的业务能力，不绕过 package 边界访问未导出成员。
	amount := money.NewAmount(12, 50)
	if amount.String() != "12.50" {
		// 失败信息保留期望值，便于区分导入问题和业务断言问题。
		t.Fatalf("金额格式不正确：got %q", amount.String())
	}
}

如果测试目录现在是仓库外的 integration/，有两个选择：把需要内部实现的测试移动到 module 根目录下，或者只通过公开服务接口测试。第二种方式更适合真正的跨模块集成测试，因为它不会把内部目录变成外部调用方的隐形依赖。

准备好目录后，用下面的命令从 module 根检查包关系。命令本身不会改变 internal 规则，它只是让错误发生在正确的模块上下文里。

# 先进入包含 go.mod 的模块根，避免把测试当成另一个模块解析
cd /path/to/payments

# 只运行当前模块下的包，观察具体哪个导入者触发了边界错误
go test ./...

外部测试包、go.work 和多模块仓库要单独检查

排查时我会依次看四件事：

• 测试文件的实际目录：不要只看 IDE 中打开的文件名，确认它是否位于允许根目录下。
• 模块声明：打开最近的 go.mod，确认测试命令使用的是预期 module，而不是嵌套 module。
• 导入字符串：它必须和 module 路径及内部目录层级一致；多一个目录或少一个目录都会变成另一个包。
• 工作区配置：存在 go.work 时，多个 module 可能同时参与解析，测试目录与 module 的归属要重新确认。

如果错误变成“找不到 module 提供的包”，先修正导入路径或模块依赖；如果明确是 internal ... not allowed，就回到目录树检查导入者。不要通过复制一份内部包、改名或增加临时 replace 来绕开边界，否则后续会出现两份实现和难以追踪的行为差异。

最后用四项清单收口

遇到 Go test 找不到内部包时，可以按这个顺序收口：第一，确认错误是否真的包含 internal 边界提示；第二，找出 internal 目录的直接父目录；第三，确认测试包的实际路径和 go.mod 所属 module；第四，从正确的 module 根执行 go test ./...。能通过公开 API 完成的跨模块测试，不要直接依赖内部实现。

这样处理后，internal 仍然承担“仓库内可复用、仓库外不可见”的边界职责，测试也能明确区分包解析问题、模块归属问题和真正的业务断言失败。

相关问题

测试包写成 package xxx_test 会导致 internal 包不能导入吗？
不会，决定权限的是测试文件所在的目录树，不是是否使用外部测试包名。

把 internal 改成普通目录能解决问题吗？
可能让导入通过，但也会取消仓库外不可导入的设计约束。先确认测试是否应该移动或改走公开 API。

为什么同一个仓库里的测试仍然被拒绝？
仓库边界和 Go 的 importer 路径不是同一个概念；嵌套 module、独立测试目录或 go.work 都可能让导入者落到允许树外。