go mod init 的 module path 必须与 Git 仓库地址完全一致，否则 go get 会失败或拉取幽灵模块；正确做法是显式指定如 github.com/username/repo，路径大小写敏感、需含 v 前缀 tag 并推送至远程。
go mod init 的 module path 必须和 Git 仓库地址完全一致
否则 go get 会拉不到代码，或拉到错误路径下的“幽灵模块”。常见错误是写成 go mod init mylib 或 go mod init ./mylib，这会导致下游用户导入时用 import "mylib" —— Go 不认这种本地名。
正确做法是先建好 GitHub/GitLab 仓库（比如 https://github.com/yourname/jsonutil），再在本地项目根目录执行：
go mod init github.com/yourname/jsonutil
生成的 go.mod 第一行必须是这个完整路径。它既是模块唯一标识，也是 go get 解析的依据。
- 路径大小写敏感：GitHub 仓库叫
JsonUtil，但模块路径写了jsonutil，就会失败 - 子目录不自动生效：如果想发布
github.com/yourname/jsonutil/encode子包，不需要额外初始化，只要主模块路径对、文件在encode/目录下即可 - 私有域名需配置
GOPRIVATE：若托管在公司内网 GitLab，外部用户要加export GOPRIVATE=gitlab.example.com/**才能go get
v1.0.0 这个 tag 必须带 v 前缀且推送到远程
unknown revision 错误 90% 出在这里。Go 不识别 1.0.0、0.1.0 或 release-1.0 这类 tag，只认 v* 开头的语义化版本。
立即学习“go语言免费学习笔记（深入）”；
打 tag 后必须显式推送：
git tag v1.0.0<br>git push origin v1.0.0
验证是否生效，换一个空目录运行：
go list -m -versions github.com/yourname/jsonutil
如果没输出或报错，检查三件事：
- Git 仓库是否设为 public（private 仓库默认不可被
go get拉取） -
go.mod文件是否在仓库根目录（不是子目录里） - tag 是否真的推上去了：
git ls-remote --tags origin | grep v1.0.0
导出符号必须首字母大写，且文档注释要放在函数/类型正上方
Go 的可见性规则很硬：小写开头的 reverse()、errCode、config 全部对外不可见，别人 import 后根本调用不到。
可导出函数示例：
// Reverse reverses a string rune-by-rune.<br>func Reverse(s string) string {<br> runes := []rune(s)<br> for i, j := 0, len(runes)-1; i < j; i, j = i+1, j-1 {<br> runes[i], runes[j] = runes[j], runes[i]<br> }<br> return string(runes)<br>}
注意：// Reverse ... 注释必须紧贴函数声明正上方，中间不能空行；否则 go doc 和 pkg.go.dev 不会收录该函数说明。
- 结构体字段也要大写：
type Config struct { Host string }，小写host string字段无法被 JSON 序列化或外部读取 - 测试文件（
*_test.go）里的辅助函数可以小写，不影响导出 - 如果模块只提供类型定义，确保类型名大写，如
type Encoder interface { ... }
go.dev 索引延迟和构建失败会导致文档不显示
即使代码已公开、tag 已打、go list 能查到版本，pkg.go.dev 页面仍可能空白或提示 “no documentation”——这不是你漏写了注释，而是索引环节卡住了。
关键检查点：
- 主分支（通常是
main或master）上的代码必须能通过go build和go test，任何编译错误或测试 panic 都会让索引中止 - 最新 tag（如
v1.0.0）对应 commit 也必须能构建成功；哪怕只有一行语法错误，整个版本都不会被抓取 - 索引有缓存：新 tag 推送后，
pkg.go.dev可能延迟几分钟到几小时才更新，不用反复刷新 - 不支持子模块独立索引：访问
pkg.go.dev/github.com/yourname/jsonutil/encode会跳转到主模块页，文档以主go.mod所在路径为准
最易被忽略的是：你本地 go test 通过了，但 CI 环境里因缺少 CGO_ENABLED=0 或平台差异导致构建失败——务必在干净环境里模拟一次 go build ./...。
