Golang如何初始化一个新的模块

go mod init 必须显式指定模块路径，如 github.com/username/project 或 example.com/myapp；不可省略域名，否则报错 malformed module path；初始化后需补全 go 版本声明并确保 import 路径与 module 一致。

go mod init 命令必须指定模块路径

初始化 Go 模块不是自动推断项目名，go mod init 后必须显式给出模块路径（module path），通常是仓库地址或唯一标识符。不填或填错会导致后续 go get、版本解析、依赖替换全部异常。

• 正确示例：go mod init github.com/username/project（推荐，与 GitHub 路径一致）
• 本地开发可暂用假域名：go mod init example.com/myapp（只要全局不冲突即可）
• 绝对不要写成：go mod init myapp（缺少域名，Go 会警告 malformed module path "myapp"）
• 模块路径一旦写入 go.mod，后续所有 import 语句都需以此为前缀，例如 import "example.com/myapp/utils"

初始化后 go.mod 文件内容需人工核对

go mod init 只生成最简 go.mod，不包含 Go 版本声明或依赖项。若项目使用较新语法（如泛型、切片操作符），缺少 go 1.18 这类声明会导致其他人构建失败或 ide 误报。

module example.com/myapp  go 1.21

• 建议立即补上 go 指令行中实际使用的 Go 版本（运行 go version 确认）
• 如果项目已有 vendor/ 或旧 Gopkg.lock，先清理再 init，否则可能残留错误约束
• go.mod 中的 module 行不能随意修改——改了就得同步更新所有 import 路径，否则编译报 import path doesn't match module path

在子目录中初始化模块要小心工作目录

Go 不支持“嵌套模块”（即一个项目里多个 go.mod 共存且相互继承）。如果在子目录执行 go mod init，就等于创建了一个独立模块，和父目录无关。这常导致依赖混乱或测试无法识别主模块。

• 想让子目录属于主模块？别在子目录 init —— 在项目根目录执行一次 go mod init 即可，子包自动纳入
• 真需要独立模块（如 CLI 工具 + SDK 分离）？确保子目录有完整 main 包，并在该目录下 go mod init，同时把父目录 go.mod 中对应路径的 replace 或 require 清掉
• 执行前用 pwd 确认当前路径，避免在 cmd/ 或 internal/ 下误操作

模块路径命名不是随便起的，它既是导入标识，也是 Go 生态中版本解析、代理缓存、私有仓库映射的依据。写错一次，后面所有人拉代码都可能遇到 unknown revision 或 cannot find module providing package。