Go包名必须全小写，因编译器强制限制且避免导出规则混淆；目录名须与package声明完全一致；模块路径变更需同步更新go.mod并做兼容处理。
Go 包名为什么不能用大写字母开头
Go 语言规范强制要求包名必须是有效的 Go 标识符，且必须全小写——这不是风格建议，而是编译器级限制。go build 遇到 MyPackage 这样的包名会直接报错：package name must be lowercase。根本原因在于 Go 的导出规则：只有首字母大写的标识符（如 FuncName、TypeName）才对外可见；包名本身不参与导出控制，用大写反而会造成语义混淆。
常见错误现象：
- 从其他语言转过来的开发者习惯性写
HTTPClient或DBUtil作包名，结果go mod tidy失败 - 在
go.mod中声明module github.com/user/MyLib，但实际目录名是mylib，导致import "github.com/user/MyLib"编译失败（路径大小写不一致）
实操建议：
- 包名用纯小写、无下划线、无数字前缀，例如：
httpclient、dbutil、yamlconf - 包所在目录名必须与
package xxx声明完全一致（包括大小写），Linux/macOS 下严格区分，Windows 虽不敏感但不可依赖 - 避免用 Go 内置包名（如
http、json、log）作自定义包名，否则可能引发 shadowing 或go list解析异常
文件系统大小写敏感对 Go 构建的实际影响
Go 工具链本身不处理文件系统大小写逻辑，但它高度依赖路径字符串的字面匹配。当你在 macOS（默认不区分大小写）开发、部署到 Linux（区分大小写）时，import "./Utils" 可能本地能编译，上线就报 cannot find package "./Utils"——因为实际目录是 utils，而 Linux 下 ./Utils 和 ./utils 是两个不同路径。
立即学习“go语言免费学习笔记（深入）”；
使用场景：
- 团队协作中有人用 Windows、有人用 macOS，提交了
pkg/Config目录，但go.mod里写的是require example.com/pkg/config v0.1.0 - Docker 构建阶段用
COPY . /app，宿主机是 macOS，镜像内是 Alpine，大小写不一致导致go build找不到包
实操建议：
- 所有 import 路径、目录名、模块路径统一用小写，禁止混用大小写命名目录或文件
- CI 流水线必须在 Linux 环境运行
go list ./...和go build ./...，提前暴露路径问题 - 用
git config core.ignorecase false强制 Git 记录大小写差异（尤其 macOS 用户），避免提交时“自动修正”大小写
如何安全地重命名一个已发布的 Go 包
Go 没有“包重命名”机制，所谓重命名本质是模块路径变更 + 兼容性过渡。如果你把 github.com/user/mytool 改成 github.com/user/my-tool，老用户 import "github.com/user/mytool" 会直接失败，除非你做兼容。
关键点在于：Go 的 import 路径 = 模块路径 + 子目录，不是文件系统路径。所以真正的操作对象是 go.mod 的 module 声明和版本标签。
实操建议：
- 先在新路径（如
github.com/user/my-tool）初始化模块，复制代码，更新go.mod中的module行 - 旧仓库保留，添加
replace github.com/user/mytool => github.com/user/my-tool v1.2.0并发布 v1.2.1，引导用户迁移 - 在新模块的
README.md显眼位置写清迁移方式，例如：import "github.com/user/my-tool/v2"（如果带 major 版本） - 切勿只改目录名不改
go.mod—— 这会导致go get仍拉取旧路径，但内部 import 又指向新路径，构建失败
vendor 目录下大小写混乱会导致什么问题
go mod vendor 会把依赖复制进 vendor/，但不会校验路径大小写是否与目标平台一致。如果某个依赖的 go.mod 里写的是 require github.com/someone/Pkg v1.0.0，而它源码里 import "github.com/someone/pkg"，vendor 后就会出现 vendor/github.com/someone/Pkg/ 目录但内部引用的是小写路径——在 Linux 上直接 go build 失败。
这类问题通常不报错，直到你运行测试或构建二进制时才暴露，定位成本高。
实操建议：
- 禁用
go mod vendor，改用GOOS=linux go build在 CI 中验证，绕过 vendor 的路径缓存干扰 - 用
go list -f '{{.ImportPath}}' all | grep -i 'Pkg\|pkg'快速扫描项目中是否混用大小写导入路径 - 如果必须用 vendor，构建前加一步检查：
find vendor -type d -name '[A-Z]*' | head -5，发现大写目录名立即排查
大小写问题从来不是“写完能跑就行”的范畴，它藏在跨平台、跨团队、跨工具链的缝隙里，一碰就碎。最省事的方式，就是从第一天起所有路径、包名、模块名全部锁定小写，不妥协、不试探。
