Go 包名和目录名不一致时 import 为什么失败

遇到“Go 包名和目录名不一致”时，先别急着改目录：这种不一致通常不会直接让 import 失败。Go 用 import path 定位目录，目录里的 package 声明决定默认调用前缀；最常见的现象是导入已经找到，但代码把目录名当成包名，最后出现 undefined。

目录导入路径和 package 声明分别决定什么

可以把一个 Go 包拆成两层看。go.mod 的模块名与相对目录拼成导入路径，例如目录是 internal/format，模块是 example.com/demo，调用方就应导入 example.com/demo/internal/format。但这个目录里的源码如果写着 package toolbox，省略别名时，调用前缀就是 toolbox，不是目录末段 format。

先区分“导入失败”和“调用名称写错”

目录名是 format、包名是 toolbox 时，下面的导入路径仍然指向正确目录，但调用必须使用 toolbox.Normalize：

package main

import (
    "fmt"
    "example.com/demo/internal/format" // 路径指向目录，不决定调用前缀
)

func main() {
    value := toolbox.Normalize("  go  ") // package toolbox 才是默认名称
    fmt.Println(value) // 只使用导出函数，避免小写标识符不可访问
}

如果写成 format.Normalize，通常得到的是 undefined: format 一类名称错误，并不说明目录不存在。真正的路径错误会发生在模块前缀、相对目录或大小写写错时。另一个独立边界是同一目录内的源码声明了不同包名，例如一部分是 package toolbox，另一部分是 package helper；这会让 Go 无法把该目录作为一个一致的包加载。

显式别名能修复调用前缀，但不能修复错误路径

如果目录不能改、又希望业务代码按目录语义调用，可以在 import 前写别名。别名只作用于当前源文件，既不会修改被导入包的真实名称，也不会改变路径解析：

package main

import (
    "fmt"
    format "example.com/demo/internal/format" // 显式指定本文件使用的前缀
)

func main() {
    value := format.Normalize("  go  ") // 这里的 format 来自别名
    fmt.Println(value) // Normalize 必须在 toolbox 包中导出
}

别名适合兼容旧代码、避免两个导入包名称冲突，或让名称更符合当前文件语境。不要为了“看起来一致”把 import 字符串改成目录以外的路径；路径必须真实对应模块中的目录，并且 internal 包还受父模块可见范围限制。

按 module、目录、包声明的顺序排查

不确定 Go 实际识别到什么名称时，可以在模块根目录查看包的导入路径、包名和物理目录：

go list -f '{{.ImportPath}} -> {{.Name}} -> {{.Dir}}' ./... # 同时查看路径、包名和目录

接着按这张清单检查：

• 路径：import 字符串是否等于 module 加目标目录，大小写是否完全一致。
• 包名：目标目录的普通 Go 文件是否使用同一个 package 声明。
• 调用：没有别名就用 package 名，有别名就用别名，并确认函数首字母大写。
• 边界：目标是不是 package main、受 internal 限制，或只在 _test.go 中存在。

这样排查的好处是不会把三个概念揉成“目录名必须等于包名”。工程上通常让两者保持一致，便于读者预测名称；确实需要不一致时，保留清晰的 package 声明，并在调用方使用显式别名即可。

常见问题

目录名和 package 名不一样，Go 一定不能 import 吗？

不一定。只要路径真实存在、目录内包声明一致且满足可见性规则，就可以导入；默认调用前缀取 package 名。

为什么 import 后写目录名会出现 undefined？

省略别名时，Go 不按目录末段生成调用前缀，而是按被导入包的 package 声明生成。可以改用真实包名或显式别名。

同一目录能放两个不同 package 吗？

普通源码文件不能这样混用；一个目录应构成一个包。测试文件的内部测试包约定是特殊规则，不应拿来组织生产源码。

显式别名会改变包本身的名字吗？

不会。它只改变当前文件引用这个包时使用的本地名称，包的导入路径和源码 package 声明都不变。