go 文件夹名与 package 声明必须严格一致，否则编译报错；main 包例外，其文件夹名仅作组织用；包名应为单个小写英文单词，避免下划线和数字。
Go 文件夹名和 package 声明必须一致
Go 编译器不认“逻辑上的包”，只按文件夹路径 + package 声明双重校验。如果文件在 ./utils 目录下，但写了 package helpers，go build 会直接报错：cannot find package "xxx/utils" 或更隐蔽的 import cycle —— 因为 Go 把它当成了另一个包。
实操建议：
- 新建文件夹前，先想好最终要写的
package名，然后用那个名字命名文件夹 - 重命名已有文件夹？别只改文件夹名，务必同步检查所有
.go文件顶部的package xxx声明 - IDE（如 VS Code + gopls）有时会缓存旧包路径，改完后执行
go mod tidy并重启语言服务器
为什么 main 包允许文件夹叫 cmd 或 app
因为 main 包不被其他包 import，它的文件夹名只是组织习惯，不影响编译。比如 ./cmd/myapp/main.go 里写 package main 完全合法；但如果你在 ./cmd/myapp/ 下写了 package server，那就不再是可执行入口，而是一个普通包 —— 此时 Go 会要求你从别的地方 import 它，且文件夹名就得匹配 server。
常见错误现象：
立即学习“go语言免费学习笔记（深入）”；
- 运行
go run ./cmd/myapp报错：no Go files in ...→ 检查该目录下所有.go文件是否都声明了package main - 误把
package main放进./internal目录 → 虽然能编译，但违反 Go 工程惯例，且go test ./internal会跳过（main包不参与测试发现）
go mod init 后改文件夹名，哪些地方会断
模块路径（module github.com/user/repo）是静态写在 go.mod 里的，和本地文件夹结构无关；但所有 import 语句都是基于模块路径 + 子目录拼出来的。所以改文件夹名，本质是改 import 路径。
实操建议：
- 改名前先全局搜索
import "github.com/user/repo/oldname"，替换成新路径 - 如果旧路径已被别人 import，就别动 —— Go 不支持“包别名重定向”，强行改等于 breaking change
-
go list -f '{{.ImportPath}}' ./...可快速列出当前项目所有实际生效的包路径，对照检查是否遗漏
小写字母、下划线、连字符这些能用在包名里吗
能编译，但不推荐。Go 规范明确建议包名用**单个、简洁、小写、无下划线的英文单词**，比如 http、json、sql。虽然 package my_utils 或 package v2 不报错，但会带来问题：
- 其他开发者看到
my_utils.SomeFunc，第一反应是这包可能没维护或不标准 - 某些工具（如
gofmt、go doc）对含下划线的包名支持不稳定 - 如果包名含数字（如
v2），又恰好有同名子目录（./v2/client），容易和版本化导入（import "example.com/lib/v2"）混淆
真正卡住的地方往往不是语法错误，而是团队协作时没人愿意去翻一个叫 pkg_v1alpha_temp_fix 的包 —— 它存在，但没人敢动，也没人记得清它到底导出了什么。
