go.mod是go模块的权威声明文件，module路径必须首行唯一且与import路径完全一致；require精确锁定版本；replace/exclude仅本地生效；go指令声明最低兼容go版本。
go.mod 不是配置文件，它是 Go 模块的权威声明 —— 编译、依赖解析、导入路径全部按它执行，改错一行就可能 go run 失败。
module 路径写错，import 就全崩
模块路径（module 第一行）必须与代码将来被 import 的路径完全一致，且只能出现在 go.mod 首行（注释除外）。常见错误包括：
-
module ./mylib或module myproject：本地路径或无域名，go get无法解析，他人也无法import -
module github.com/user/repo/（末尾带斜杠）：Go 直接拒绝加载，应为module github.com/user/repo - 路径含大写字母或下划线（如
MyApp_v1）：部分工具（如go list -m all）行为异常，官方明确不推荐 - 本地调试时随意改
module名：已有的import "old/path"全部报错import path does not match module path
require 版本不是“建议”，而是精确锁定
require 列出的是直接依赖及其**精确版本**，Go 不会自动升级，也不接受模糊语义（比如 v1.2.x 或 latest）。它支持三种合法格式：
- 标准语义化版本：
github.com/gin-gonic/gin v1.9.1 - 伪版本（commit 级锁定）：
golang.org/x/net v0.23.0-20240522172620-85d65e11e3f1 - 主干快照（仅限未打 tag 的分支）：
github.com/sirupsen/logrus master或github.com/sirupsen/logrus main（需加incompatible标记）
go mod tidy 只补全代码中实际 import 了的依赖；没被引用的包，哪怕出现在 go.sum 里，也不会进 require。如果某依赖只在测试中用到，go mod tidy 会标上 // indirect —— 这不是冗余，而是 Go 的最小版本选择（MVS）结果。
replace 和 exclude 是临时手术刀，不是常规配置
replace 和 exclude 仅在当前模块生效，不会传播给下游依赖，且极易引发隐性问题：
-
replace github.com/old/pkg => ./local-pkg：只影响本项目构建，别人go get你的模块时仍走原始路径 -
exclude github.com/old/pkg v1.9.0：仅阻止该版本被选中，若其他依赖显式 require 它，go build仍可能失败 - 多个
replace映射到同一本地路径 → 报错replaced by multiple modules - 生产环境长期用
replace替换标准库（如golang.org/x/sys）→ 可能因 ABI 或行为差异导致 runtime panic
它们的存在意义很窄：本地调试 fork 后未发版的修复、绕过某个已知 panic 的 patch 版本。一旦问题解决，应立刻删掉。
go 指令决定语言特性可用边界
go 1.21 这类声明不是“建议使用的 Go 版本”，而是**最低兼容版本**，直接影响：
- 语法可用性：若用了 Go 1.22 新增的
type alias，但go.mod写着go 1.21，go build直接报错 - 工具链行为：
go list -m all输出格式、go mod graph的边规则，在不同 Go 版本下有差异 - 模块验证逻辑：Go 1.22+ 对
// indirect依赖的处理更严格，旧版go.mod升级后可能触发新校验
它不强制你升级 Go，但如果你用新特性，就必须同步更新这行。别写成 go 1.26（当前最新是 1.26，但未来会变），而应写项目真正依赖的最低版本。
最容易被忽略的点是：module 路径和 import 路径必须一字不差，且 go.mod 一旦生成，它就不是“可商量”的配置，而是 Go 工具链执行时的唯一事实来源 —— 错误不在代码里，而在那一行 module 声明中。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
