根本原因不是文件“不一致”，而是go构建系统要求replace指向的本地目录必须包含合法go.mod文件且module名与原库完全一致，否则忽略该替换；需确保go.mod顶格书写、无注释、路径无空格中文，并执行go mod tidy校验。
直接结论：不是文件“不一致”，而是 Go 构建系统拒绝使用未被 go.mod 显式声明或未通过 go mod tidy 验证的本地修改 —— 你改了代码但没告诉 Go “这版我认”。
go build 报错 no required module provides package
这是最典型的现象：你把某个依赖库 clone 到本地、改了几行，然后在 go.mod 里加了 replace github.com/a/b => ./local/b，但 go build 仍失败，提示找不到包。
- 根本原因不是路径写错，而是
./local/b目录下没有有效的go.mod文件（哪怕只有一行module github.com/a/b） -
replace不是“复制粘贴”，而是构建时做路径映射；Go 要求目标路径必须是一个合法模块（含go.mod），否则直接跳过、当作不存在 - 常见误操作：直接改
~/go/pkg/mod/github.com/a/b@v1.2.3下的源码 —— 这类修改对构建完全无效，因为go build不读缓存目录里的源码，只读replace指向的路径或模块本身
replace 后 go list -m all 不显示本地路径
执行 go list -m all | grep a/b 仍显示原始远程路径和版本，说明 replace 没生效。
- 检查
go.mod是否在项目根目录（即运行go build的当前目录），且该文件被修改后保存 -
replace行末不能有注释（Go 解析器会忽略整行），也不能缩进 —— 必须顶格写：replace github.com/a/b => ./local/b - 如果本地路径含空格或中文，
go mod tidy会静默失败，但不报错；建议全用英文路径 - 执行一次
go mod tidy（即使没报错）—— 它会校验replace目标是否可解析，并更新go.sum，否则构建时可能回退到远程版本
vendor 目录存在时 replace 失效
项目里有 vendor/ 目录，但 replace 指向的本地修改始终不被使用。
-
go build默认启用 vendor 模式（当存在vendor/modules.txt时），此时它只从vendor/读依赖，完全忽略replace - 临时解决：加
-mod=mod参数强制走模块模式：go build -mod=mod - 长期方案：删掉
vendor/目录，或执行go mod vendor重新生成 —— 注意，新生成的vendor/会把replace目标也拷进去，所以必须先确保replace已生效且go list -m all显示正确路径 - CI 环境中尤其要注意：有些 CI 脚本默认执行
go mod vendor，这会覆盖你的本地调试意图
本地修改后编译成功但运行时 panic
build 成功，但一调用刚改的函数就 panic: interface conversion: interface {} is nil 或类似类型错误。
- 大概率是本地模块的
go.mod中module名与原库不一致（比如写成module local/b），导致导入路径不匹配 —— Go 认为这是另一个包，类型不互通 - 确认
./local/b/go.mod第一行必须是module github.com/a/b（与原库完全一致），否则所有 import 都会失败 - 检查是否有未提交的 git 修改：Go 在构建时会读取
git describe --tags生成伪版本号，如果本地有 uncommitted change，可能导致版本号不稳定，间接影响依赖解析 - 改完务必跑
go test ./...，尤其是涉及接口、导出符号变更时，仅编译通过不代表行为正确
真正卡住人的地方，往往不是语法或命令写错，而是 Go 对“模块合法性”的隐式要求太严格：一个没 go.mod 的目录、一行多出的空格、一次忘记 go mod tidy，都会让本地修改彻底失效。别信“我改了就应该起作用”，得让 Go 明确看见、承认、并记录下来。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
