go mod init 是必做动作，因 Go 1.11+ 默认启用模块模式，未初始化模块时无法解析本地导入路径如 "myproject/utils"，仅认标准库或远程包。
package 是 Go 代码组织的最小单位，module 是依赖和版本管理的最小单元——二者分工明确，不能混用，也不能跳过模块直接发布包。
为什么 go mod init 不是可选项，而是启动项目的必做动作
Go 1.11+ 默认启用模块模式（GO111MODULE=on），不初始化模块就写 import "myproject/utils"，编译会报错：import "myproject/utils": cannot find module providing package myproject/utils。
这不是路径问题，而是 Go 拒绝在无模块上下文中解析本地导入路径。
必须执行：
go mod init myproject
生成 go.mod 后，Go 才认可 "myproject/utils" 这类相对模块路径为合法导入。否则它只会认标准库或已下载的远程路径（如 "fmt" 或 "github.com/sirupsen/logrus"）。
常见错误：
- 在子目录下执行
go mod init→ 模块名变成subdir，导致上级main.go导入失败 - 模块名用了非法字符（如大写字母、中划线）→ 后续
go get或发布到私有仓库时出错 - 没删掉旧的
vendor/或残留GOPATH配置 → 行为不一致，尤其在 CI 环境中静默失败
package name 和目录名不一致会怎样
可以不一致，但强烈不建议。例如目录叫 mathutil，文件却写 package calc：
- 编译通过，但
import "myproject/mathutil"仍要求该目录下所有文件声明package mathutil； - 如果你误写成
package calc，Go 会报错：found packages mathutil and calc in /path/to/mathutil。
更隐蔽的问题：
- IDE（如 VS Code + gopls）可能无法正确索引导出符号
- 运行
go list -f '{{.Name}}' ./mathutil返回calc，但外部 import 路径仍是"myproject/mathutil"，造成认知割裂 - 测试文件（
*_test.go）若与源文件 package 名不同，go test会跳过或报错
第三方模块引入后，go.mod 和 go.sum 分别管什么
go.mod 记录你「声明要什么」：模块路径、Go 版本、显式依赖及其精确版本（如 github.com/gin-gonic/gin v1.9.1）。go.sum 记录你「实际拿到的是什么」：每个依赖模块的校验和（h1:...），用于防止下载被篡改的包。
关键行为：
-
go mod tidy会自动补全缺失依赖、删除未使用依赖，并更新go.mod；但它不会重写go.sum已存在的条目——除非你删了它再跑 tidy - 如果
go.sum中某行校验和不匹配（比如别人改了 tag 内容又重推），go build直接失败，提示checksum mismatch - 私有模块（如
git.example.com/internal/auth）也必须出现在go.sum中，否则go run会卡住或报 403
本地包开发时，如何避免反复 go mod tidy 和版本冲突
当你一边改 myproject/utils，一边在 main.go 中用它，又不想发版，最稳的方式是用 replace：
go mod edit -replace myproject/utils=../utils
这会在 go.mod 中插入：
replace myproject/utils => ../utils
效果：
- Go 编译时直接读取本地
../utils目录，跳过模块缓存和版本检查 - 修改
utils里的函数，go run .立即生效，无需go mod tidy - 上线前删掉
replace行，再go mod tidy发布正式版本即可
注意：replace 只对当前模块生效，不影响下游项目；如果下游也想用你的本地版，得在它的 go.mod 里单独加 replace。
模块路径不是文件路径，import 字符串不是相对路径——这是绝大多数初学者卡住超过 2 小时的根源。
