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