go mod download 报 checksum mismatch 是因本地修改依赖后 go.sum 哈希与实际内容不匹配；正确解法是用 replace 指向含合法 go.mod 的本地路径，并配合 exclude 防止多版本冲突，再运行 go mod tidy 更新校验和。
为什么 go mod download 会报 checksum mismatch 错误
当你在本地修改了某个依赖模块的代码（比如打 patch、调试源码），又没走正确的流程，go build 或 go mod download 就会校验失败，报类似这样的错误：checksum mismatch for module github.com/some/pkg。根本原因是 Go 的校验机制发现你本地 go.sum 记录的哈希值，和当前实际文件内容不一致——它默认信任远程 tag/commit，不信任你手改的代码。
绕过校验不是解法，要用 replace + exclude 组合
直接删 go.sum 或用 -mod=mod 强制忽略校验，短期能跑通，但后续 CI/其他机器上必然崩。正确做法是让 Go 明确知道：“这个模块我就是要用本地路径”，同时避免校验冲突：
- 用
replace github.com/some/pkg => ./local-fork把依赖指向你本地修改后的目录（路径必须存在且含go.mod） - 如果该模块在依赖树中被多个版本拉入，还要加
exclude github.com/some/pkg v1.2.3，防止旧版本被自动选中触发校验 -
replace后必须运行go mod tidy，否则go.sum不会更新为本地路径的哈希
本地模块必须有合法的 go.mod 文件
很多人把源码拷到本地目录就 replace，结果 go mod tidy 报错或仍校验失败。关键点是：./local-fork 目录下必须有有效的 go.mod，且其中 module 行要和原模块名完全一致（比如 module github.com/some/pkg）。如果原模块用了语义化版本，你还得确保本地 go.mod 的 require 声明不冲突；若只是临时调试，可删掉所有 require 行，只留 module 和 go 版本声明。
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
CI 和协作时怎么安全地共享本地修改
直接提交 replace 到主分支会破坏其他人环境。推荐两种场景化处理：
- 临时调试：用
go mod edit -replace=github.com/some/pkg=./local-fork修改go.mod，调试完再go mod edit -dropreplace=github.com/some/pkg撤回 - 团队共用 patch：把本地修改推到私有 fork 分支，用
replace github.com/some/pkg => github.com/your-org/pkg v1.2.3-myfix，并在go.mod中require该分支版本——这样go.sum能正常生成，也不污染主干
真正麻烦的从来不是改代码，而是让 Go 工具链“相信”你改得有理有据。replace 不是 bypass，是显式声明意图；exclude 不是删记录，是切断歧义路径。漏掉任一环，下次 go mod vendor 或换机器拉代码时，照样报错。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
