go mod init 的模块路径必须一步到位使用真实远程地址，如 github.com/yourname/mymodule；v2+ 版本须在路径末尾加 /v2 并同步打对应 tag；打 tag 前需提交 go.mod/go.sum 且确保 clean；子模块独立发布需其目录下有匹配路径的 go.mod。
go mod init 之后模块路径不能随便改
模块路径一旦在 go mod init 中指定，就决定了外部引用的完整导入路径，比如 github.com/yourname/mymodule。后续所有发布、打 tag、被 go get 引用都依赖这个路径。改了路径等于换了个新模块，旧版本无法升级，老用户会拉不到更新。
常见错误现象：本地测试时用 go mod init mymodule，推到 GitHub 后才发现路径应为 github.com/yourname/mymodule，硬改 go.mod 里的 module 行会导致 go list -m 显示不一致、go get 失败、CI 构建报 invalid module path。
- 初始化必须一步到位：用真实远程仓库地址作为模块路径，例如
go mod init github.com/yourname/mymodule - 如果已错，不要直接改
go.mod；应新建干净目录，重新go mod init，再迁移代码 - 模块路径中不能含大写（Go 不区分大小写但工具链可能出错），也不能含空格或特殊字符
v2+ 版本必须带 /v2 路径后缀
Go 对主版本升级有硬性约定：v2 及以上必须在模块路径末尾显式添加 /v2（或 /v3 等），否则 go get 会拒绝识别为新主版本，仍当作 v1 使用。
例如，从 v1 升级到 v2，不是简单打个 v2.0.0 tag 就完事，还必须改 go.mod 的 module 行：
module github.com/yourname/mymodule/v2
同时，使用者导入时也必须写全路径：import "github.com/yourname/mymodule/v2"。这是 Go 模块隔离不同主版本的唯一机制。
- 路径后缀和 tag 名称必须严格对应：tag 是
v2.0.0，路径就必须是/v2；若打v2.0.0但路径仍是/v1，Go 会忽略该 tag - v0.x 和 v1.x 不需要后缀，但 v1.0.0 之后的所有破坏性变更，只能走 v2+/路径后缀方案
- 不要试图用
replace绕过路径规则——它只影响本地构建，不影响他人go get
打 tag 前必须确保 go.mod/go.sum 已提交且 clean
Go 拉取模块时，实际下载的是 tag 对应 commit 的整个快照，其中 go.mod 和 go.sum 是版本可信的核心依据。如果 tag 里这两文件缺失、未提交，或 go.sum 缺少哈希值，下游 go get 会失败或触发 go mod download 时校验失败。
典型问题：开发者在本地 git tag v1.0.0 后直接 git push origin v1.0.0，但忘了先 git add go.mod go.sum && git commit —— 导致 tag 指向的 commit 不含这些文件。
- 打 tag 前务必运行
go mod tidy，确保go.mod和go.sum一致且无冗余 - 提交这两个文件后再打 tag：
git add go.mod go.sum && git commit -m "chore: update deps for v1.0.0"，再git tag v1.0.0 - 推送时要显式推送 tag：
git push origin v1.0.0，别只推分支 - 验证方式：在空目录下执行
go mod init test && go get github.com/yourname/mymodule@v1.0.0，看是否成功
子模块独立发布必须满足三个硬条件
所谓“子模块”，比如 github.com/user/repo/submod，想单独发版（如 v1.2.3）而不动主模块，不是靠 Git 子模块或 replace 实现的，而是靠 Go 模块自身的路径解析逻辑——它要求子目录本身就是一个合法模块。
最容易踩的坑是：在子目录里没运行 go mod init，或者 go.mod 里的 module 声明路径与实际引用路径不一致，导致 go get github.com/user/repo/submod@v1.2.3 报 unknown revision 或 no matching versions。
- 子目录必须有自己独立的
go.mod，且module行必须精确匹配引用路径，例如module github.com/user/repo/submod - tag 必须打在该子目录有变更的 commit 上（即该 commit 中
submod/下文件确实被修改过），否则 Go 认为“无变化”，跳过该 tag - 主模块根目录的
go.mod中，**不能**require自己的子模块路径，否则会把子模块当成主模块的一部分，失去独立版本意义
真正卡住多数人的，从来不是命令记不住，而是对模块路径、tag 位置、go.mod 内容三者之间的一致性缺乏敬畏——差一个字符、少一次提交、错一个斜杠，下游就拉不到东西。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
