go模块名必须是代码托管地址的完整路径（去协议和.git），如github.com/user/repo，它决定导入路径与依赖解析，错误命名将导致构建失败、依赖混乱及高迁移成本。
Module 名必须能唯一标识项目，且与代码实际托管位置一致
Go 的 go mod init 生成的 module name 不是“项目名”或“服务名”，而是 Go 包导入路径的根。它决定了其他项目用什么路径 import 你的代码，也影响 go get 能否正确拉取。如果填错，后续改名成本极高——所有 import 语句、CI 脚本、依赖管理工具（如 go list -m all）都会出问题。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 直接用代码仓库的完整 HTTPS 地址（去掉协议头和 .git 后缀），例如 GitHub 项目
https://github.com/user/repo→ module name 就是github.com/user/repo - 公司内网 GitLab 或私有 Git 服务器，同样照搬域名 + 路径，如
gitlab.internal.company.com/team/project - 绝对不要用
myproject、backend、v1这类无上下文的名字——它们无法被 Go 工具链解析，go build会报cannot find module providing package - 如果项目暂无远程地址（比如本地 PoC），可用临时域名如
example.com/project，但上线前必须替换为真实托管地址，否则别人无法复现依赖
子模块（submodule）命名不能靠目录结构自动推导
Go 没有“子 module”的概念。一个 repo 只应有一个顶层 module，即 go.mod 所在目录的 module name。常见误解是：把 cmd/、internal/、pkg/ 下的目录当成独立 module，然后分别 go mod init ——这会导致多个 go.mod 文件共存，go build 时随机选错根，报 missing go.sum entry 或 import path doesn't contain a vendor directory。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 整个 repo 只在根目录运行一次
go mod init github.com/user/repo，所有子目录包都以该 module 为前缀导入，如github.com/user/repo/pkg/util - 需要逻辑隔离？用 Go 原生方式：按目录分包，不新建 module；需要版本控制粒度？拆成独立 repo，各自有完整 module path
- 如果误建了嵌套
go.mod，删掉子目录下的go.mod和go.sum，再在根目录执行go mod tidy
公司内部域名命名要提前对齐 DNS / Git 权限体系
用 company.com/project 看似简洁，但实际会卡在三个地方：DNS 解析失败导致 go get 超时；Go 工具默认只信任 HTTPS，而内网域名常走 HTTP；Git 认证方式（SSH vs HTTPS）与 module path 不匹配，拉取时提示 unknown revision 或 permission denied。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 优先使用 Git 服务器真实可访问的域名，例如 GitLab 实例是
git.company.internal，那就用git.company.internal/team/proj，而不是幻想中的company.com/proj - 若必须用泛域名（如
corp.company.com），确保该域名已配置为公司内网可解析，并在~/.gitconfig中配好 credential helper，或在go env -w GOPRIVATE=corp.company.com告诉 Go 跳过校验 - 避免用
localhost、127.0.0.1、file://开头的 module name——它们在 CI 或他人机器上必然失败
别为了“好看”缩写或重定向 module path
有人把 github.com/owner/very-long-project-name 缩成 github.com/owner/vlpn，或者用 CNAME 把 g.corp.com 指向 gitlab.corp.com 再当 module name 用。Go 工具链不识别 DNS CNAME，也不理解业务缩写，只会按字面路径找仓库，结果就是 go get 报 repository not found，而且错误信息里根本不会提示“你缩错了”。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- module name 必须和
git clone的 URL 路径完全一致（忽略协议和 .git 后缀） - 想简化导入路径？用 Go 的 alias 导入：
import util "github.com/user/repo/pkg/util"，而不是动 module name - 已发布 module 需改名？只能发新版本（如 v2+），并在新路径下重新初始化，旧路径保留兼容性，不能直接覆盖
最常被忽略的一点：module name 一旦出现在公开 go.sum 或他人项目的 go.mod 里，就等于固化为接口契约。改它比改 API 还重，动手前先查一遍 go list -m -f '{{.Path}} {{.Version}}' all | grep 你的旧名。
