go.mod 的 module 声明必须位于首行（注释除外），唯一定义模块根路径；require 版本需可解析，支持语义化版本与伪版本；replace/exclude 仅本地生效；go 指令声明最小 Go 版本，影响语法与工具行为；indirect 标记由 go mod tidy 自动添加。
go.mod 文件的 module 声明必须是第一行
Go 模块的根路径由 module 指令唯一定义，它必须出现在 go.mod 文件首行（注释除外），且只能出现一次。这个路径不仅是模块标识符，还直接影响 go get 的导入解析和版本发布时的语义化路径。
常见错误包括：
- 在
module前写了空行或非注释内容 →go mod tidy会报错go.mod:1: unknown directive "require" - 路径末尾带斜杠（如
module github.com/user/repo/）→ Go 会拒绝解析，应为module github.com/user/repo - 本地开发时随意改
module名 → 导致已有import路径失效，编译报import path does not match module path
require 指令中的版本号必须可解析
require 列出的是直接依赖及其版本约束，但 Go 并不强制要求所有条目都对应真实发布的 tag。它可以是：
- 语义化版本（如
github.com/sirupsen/logrus v1.9.3） - 伪版本（如
golang.org/x/net v0.23.0-20240522172620-85d65e11e3f1），用于 commit 级别锁定 - 主干快照（
latest不被允许；必须用master或main分支名 ++incompatible标记）
注意：go mod tidy 会自动补全缺失的 require 条目，但若某依赖在代码中未被实际 import，它不会被加入 —— 即使 go.sum 里有其校验和。
立即学习“go语言免费学习笔记（深入）”；
replace 和 exclude 只在当前模块生效
replace 和 exclude 是调试与临时绕过机制，不参与模块传播：
-
replace github.com/old/pkg => ./local-pkg：仅影响本模块构建，下游依赖仍按原始路径解析 -
exclude golang.org/x/text v0.14.0：阻止该版本被选中，但若其他依赖显式 require 它，go build仍可能失败 - 多个
replace冲突时（如不同路径映射到同一本地目录），Go 会报错replaced by multiple modules
生产环境应避免长期使用 replace，尤其不要用于标准库或核心生态包（如 golang.org/x/sys），容易引发隐性不兼容。
go 指令决定模块行为兼容性
go 指令（如 go 1.21）声明本模块支持的最小 Go 版本，它影响：
- 语言特性可用性（如泛型、切片
clear()函数） -
工具链行为（
go list -m all输出格式、go mod graph的边规则） - 模块验证逻辑（Go 1.22+ 对
// indirect依赖的处理更严格）
如果项目用了 Go 1.22 新增的 type alias 语法，但 go.mod 写着 go 1.21，go build 会直接报错，而不是静默降级。
module example.com/myapp
go 1.22
require (
github.com/google/uuid v1.3.1
golang.org/x/net v0.23.0
)
require golang.org/x/crypto v0.22.0 // indirect
replace golang.org/x/net => ../net-fix
真正容易被忽略的是 indirect 标记的来源 —— 它不是手动写的，而是 go mod tidy 自动添加的，表示该依赖未被当前模块直接 import，但被其他依赖所依赖。删掉它可能让构建突然失败，因为 go 工具链不再保证其存在。
