Go模块（go.mod）是Go 1.11起的官方包管理标准，取代GOPATH模式，允许任意目录初始化模块并记录依赖版本；错误嵌套模块、路径不一致或缺失go.mod会导致构建失败或导入错误。
什么是 Go 模块（go.mod）而不是 GOPATH
Go 1.11 起模块（go mod）成为官方包管理标准，它取代了旧的 GOPATH 工作模式。你不再需要把项目放在 $GOPATH/src 下；任意目录下执行 go mod init 就能初始化模块。模块根目录下会生成 go.mod 文件，记录模块路径和依赖版本。
常见错误：在已有 go.mod 的子目录里重复运行 go mod init，会创建嵌套模块，导致构建失败或导入解析混乱。
- 模块路径（如
github.com/yourname/mylib）应与代码未来可能被import的路径一致 - 若只是本地开发、不发布，路径可以是任意合法字符串（如
myproject），但别用main或保留字 -
go mod tidy会自动补全依赖并清理未使用项，建议每次增删 import 后运行
如何正确组织 Go 包结构
Go 中“包”由目录内所有 .go 文件共同组成，包名（package xxx）只需在同一目录下统一即可，不要求与目录名相同——但强烈建议保持一致，否则 import 时容易混淆。
典型结构示例：
立即学习“go语言免费学习笔记（深入）”；
监控一个或多个 GitCode 仓库的 PR，通过 OpenClaw Gateway 自动执行 AI 审查，发布 PR 评论，并发送钉钉和企业微信通知。
myapp/
├── go.mod
├── main.go // package main
├── cmd/
│ └── myapp/
│ └── main.go // package main —— 可单独构建为二进制
├── internal/
│ └── parser/
│ ├── parser.go // package parser
│ └── ast.go // package parser
└── pkg/
└── util/
└── strings.go // package util
-
internal/下的包只能被本模块导入，Go 编译器强制限制外部模块无法引用 -
cmd/用于存放可执行命令，每个子目录通常含一个main包 - 避免在
main包中写业务逻辑；核心逻辑应放在独立包（如pkg/或internal/）中
如何发布与复用自定义包
要让别人 import "github.com/yourname/mypkg"，你需要：把代码推送到公开 Git 仓库（如 GitHub），确保模块路径匹配远程地址，并打语义化版本 tag（如 v0.1.0）。
使用者执行 go get github.com/yourname/mypkg@v0.1.0 即可拉取指定版本，go.mod 会自动记录该依赖。
- 本地测试时，可用
replace重定向模块路径：replace github.com/yourname/mypkg => ../mypkg - 私有仓库需配置 Git 凭据或
git config设置url."ssh://git@github.com".insteadOf等，否则go get会卡在认证环节 - 如果包没有
go.mod，Go 会尝试用gopkg.in或旧式GOPATH方式解析，行为不可控，务必自己初始化模块
为什么 go build 找不到你的包
最常见原因是：当前工作目录不在模块根目录，或 go.mod 中模块路径与实际 import 路径不一致。例如模块定义为 module example.com/foo，但代码里写了 import "example.com/bar"，就会报错 cannot find module providing package。
- 运行
go list -m查看当前模块路径是否符合预期 - 用
go list -f '{{.Dir}}' <code>my/import/path检查 Go 是否能定位到该包目录 - Windows 下注意路径分隔符不影响 import，但
replace中的本地路径要用正斜杠或双反斜杠 - IDE（如 VS Code + Go extension）有时缓存旧的模块信息，可删掉
go.sum和go.mod重新go mod init
模块路径不是 URL，也不是文件系统路径，它是逻辑标识符——写错一个字符，整个依赖图就断了。这点比多数语言更严格，也更不容妥协。
