go build -ldflags 注入版本信息是轻量可控的首选方案，需配合 Git tag 与 go.mod 一致，Version 变量须定义在可导出包中（如 main.Version），-X 参数格式为 importpath.name=value，推荐用 git describe --tags --exact-match 提取语义化版本，CI 应校验 SemVer 并拒绝 dirty 版本，goreleaser 配置中 tag、module 路径、-ldflags 和 version 字段必须严格统一。
go build -ldflags 注入版本信息是轻量、可控、无需第三方工具的首选方案，但必须配合 Git tag 和 go.mod 保持一致，否则运行时输出和模块解析会脱节。
如何用 go build -ldflags 注入可运行时读取的版本变量
核心是让二进制在启动时能打印出真实版本，而不是写死字符串或依赖构建环境变量。
-
Version变量必须定义在可导出包中（首字母大写），例如main.Version或github.com/user/proj/internal/version.Version - 构建命令中
-X参数格式严格为importpath.name=value，路径错一位（比如漏掉main.或写成./main.Version）变量就不会被覆盖 - 推荐统一用
git describe --tags --exact-match 2>/dev/null || echo "dev"提取版本，避免git rev-parse HEAD生成的哈希无法体现语义化含义 - macOS 的
date不支持%s，跨平台建议用$(date -u +%Y-%m-%d)而非$(date +%s)
go.mod 中的 module 行不是版本号，别把它当发布标识
go.mod 的 module github.com/user/repo/v2 只影响导入路径兼容性，不参与构建产物标记。很多人改完这行就以为“已发布 v2”，结果 ./myapp --version 还是 dev。
- 模块路径中的
/v2是 Go 模块系统识别 major 版本的强制约定，但它本身不携带版本号（如v2.1.0） - 真正对外暴露的版本号，必须由构建流程注入到变量里，并由程序自身输出（例如
fmt.Println("v", version.Version)） - 若想让
go list -m显示当前版本，必须打 Git tag（如v2.1.0），且该 tag 必须指向含有效go.mod的 commit，并已git push origin v2.1.0
CI 中自动提取版本并注入，避免本地手误
手动传 -ldflags 容易漏参数、拼错路径、忘记更新 tag。CI 流程应把版本来源和构建动作解耦。
- 优先从 Git tag 提取：用
git describe --tags --exact-match判断是否为干净 tag；若失败则 fallback 到dev或带距离的 dirty 版本（如v1.2.0-3-gabc123），但生产发布应拒绝 dirty 版本 - 不要解析提交信息（如
${{ github.event.head_commit.message }}）来取版本——提交信息不可靠，tag 才是权威来源 - 构建前加校验步骤：运行一个小型
go run cmd/check-version/main.go，检查Version是否非空、是否符合 SemVer（可用github.com/blang/semver/v4） - GitHub Actions 触发条件务必写成
push: tags: ['v*']，而非tags: ['*']，否则1.2.0这类无v前缀的 tag 会被忽略
用 goreleaser 发布多平台二进制时，容易漏掉的关键配置
goreleaser init 只生成骨架，几乎所有关键字段都要手动补全，否则产物缺失或不可用。
立即学习“go语言免费学习笔记（深入）”；
-
builds[].main必须指定实际入口路径（如./cmd/myapp/main.go），不能留空或填错目录 -
builds[].binary要匹配目标平台习惯：Windows 下必须带.exe后缀（myapp.exe），否则 zip 包里双击无效 -
builds[].goos和goarch需显式列出全部目标组合（如linux/amd64,darwin/arm64,windows/386），默认值不全，漏一项就少一个平台包 -
archives[].format: zip要显式添加，尤其对 Windows 用户，tar.gz在资源管理器里无法直接解压 -
checksums和sign不是可选项：下游用户靠checksums.txt校验完整性，靠 GPG 签名确认来源可信——这两项一旦跳过，发布即失去可信基础
go.mod 路径、-ldflags 注入值、goreleaser 配置里的 version 字段，这四者必须严格一致；任何一处脱节，都会导致用户看到的版本号、能拉到的模块版本、实际运行的二进制标识三者不统一。 
