模块名必须与未来实际导入路径一致，如打算用 import "github.com/yourname/myapp/utils"，则需执行 go mod init github.com/yourname/myapp，不可用本地路径、短名或拼写错误。
直接在项目根目录执行 go mod init 即可初始化模块，但模块名必须与未来代码实际导入路径一致，否则后续 import 会失败或引发循环依赖。
go mod init 后模块名写什么？
模块名不是随便起的，它等价于你将来在其他地方 import 这个项目的路径前缀。比如你打算让别人用 import "github.com/yourname/myapp/utils"，那初始化时就必须写：
go mod init github.com/yourname/myapp
常见错误包括：
- 写成本地路径如
go mod init ./myapp（Go 不支持） - 写成短名如
go mod init myapp（会导致 import 路径不匹配，go build报cannot find module providing package） - 写错大小写或拼写，和真实 GitHub/GitLab 地址不一致（Git 仓库地址变更后，
go get会拉错版本）
项目目录结构怎么组织才符合 Go 惯例？
Go 官方不强制结构，但社区共识是按功能分层，避免把所有文件塞进根目录。典型结构如下：
myapp/
├── go.mod
├── main.go
├── cmd/
│ └── myapp/
│ └── main.go
├── internal/
│ └── service/
│ └── user.go
├── pkg/
│ └── utils/
│ └── helper.go
└── api/
└── v1/
└── handler.go
关键点：
-
cmd/下放可执行入口，每个子目录对应一个二进制（利于多命令项目，如cmd/server和cmd/cli） -
internal/仅限本模块内部使用，外部无法 import（Go 编译器强制保护） -
pkg/是有意暴露给外部复用的公共包（命名需稳定，API 变更需考虑语义化版本） - 根目录
main.go应极简，只做cmd/myapp/main.go的符号链接或弃用，避免混淆构建入口
go mod init 后立即要做的三件事
初始化只是起点，不补全这三项，后续开发大概率卡住：
- 运行
go mod tidy：自动补全依赖、清理未使用项，并生成go.sum - 检查
go.mod中go版本是否匹配本地go version；若不一致（如写go 1.20但本地是1.22），建议显式升级：go mod edit -go=1.22 - 确认
GOPROXY设置合理，国内推荐：export GOPROXY=https://goproxy.cn,direct，否则go get可能超时或 404
模块名一旦写进 go.mod，就决定了整个项目的 import 路径契约；改名不是改一行那么简单，得同步更新所有 import 语句、CI 脚本里的路径、文档示例，甚至已发布的 tag。一开始想清楚再敲下 go mod init。
