unknown revision 错误主因是远程仓库缺失所 require 的 tag，非网络问题；应先用 git ls-remote --tags 验证 tag 存在性，再通过 commit hash 临时替代或联系维护者补打 tag，replace 指向本地路径需在 ci 前移除以避免构建失败。
go mod tidy 报 unknown revision 错误
这是标签丢失最典型的表征：Go 工具链能定位到模块仓库，但找不到你 require 里写的那个 tag（比如 v1.2.0），于是报 unknown revision v1.2.0 或类似提示。
根本原因不是网络或代理问题，而是远程 Git 仓库里压根没打这个 tag，或者 tag 被 force-push 删除过。
- 先用
git ls-remote --tags <repo-url></repo-url>直接查远程有没有该 tag（例如git ls-remote --tags https://github.com/cloudwego/hertz.git） - 如果返回为空或不包含你要的版本，说明 tag 确实不存在——这时不能硬等，得换策略
- 临时方案：改用 commit hash 替代 tag，如
go get github.com/cloudwego/hertz@3a7f1b2（确保该 commit 在主分支上且稳定） - 长期方案：联系模块维护者补打 tag，或在自己项目中
replace到一个已存在的、功能等价的 tag 或分支（如main）
replace 指向本地路径后 CI 构建失败
开发时用 replace github.com/xxx/yyy => ./local/yyy 很方便，但 CI 环境没有 ./local/yyy 这个目录，直接报 no required module provides package。
Golang Spf13 Viper
下载
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
-
replace不会自动传播，只对当前模块生效，CI 里也不会去猜你本地路径 - 上线前必须删掉或注释掉
replace行，再跑一次go mod tidy确保require指向可公开访问的版本 - 若必须保留本地调试能力，建议用两个 go.mod 文件：开发用
go.mod.dev（含 replace），CI 用标准go.mod；通过go mod edit -dropreplace=xxx在构建前清理 - 更稳妥的做法是：把本地模块也推到私有仓库，然后
replace改成指向那个私有地址（如git.example.com/internal/yyy），再配好GO_PRIVATE
go.sum 缺失导致 build -mod=readonly 失败
启用 -mod=readonly 后报 missing go.sum entry for module，常被误认为是依赖没拉全，其实是校验文件不完整。
-
go.sum不是缓存，是每个require的 checksum 清单；只要go.mod里有某行，go.sum就必须有对应条目 - 常见诱因：手动编辑了
go.mod但没运行go mod download或go mod tidy，导致go.sum没同步更新 - 修复命令顺序很重要：先
go mod download（补全缺失模块并生成 sum 条目），再go mod tidy（清理冗余），最后git add go.sum - CI 中遇到此错，90% 是因为没拉最新
go.sum，或缓存了旧版 —— 不要跳过git checkout步骤
vendor 目录里模块版本和 go.mod 不一致
执行 go mod vendor 后发现 vendor/ 里某个包的代码版本跟 go.mod 写的不一样，甚至编译失败。
-
go mod vendor默认只拷贝go list -deps计算出的最终解析版本，不保证和require行完全一致（尤其当存在indirect或 MVS 升级时） - 检查实际使用的版本：运行
go list -m -f '{{.Path}} {{.Version}}' all | grep xxx，对比输出和vendor/xxx/go.mod里的module声明 - 强制锁定 vendor 内容：在
go.mod中显式require所需版本，并确保没有replace干扰；必要时加// indirect注释提醒自己这是被间接拉入的 - 提交
vendor/前务必验证：go build -mod=vendor和go test -mod=vendor都要通过
go mod tidy 自动兜底——它只做同步，不负责找补。golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
