replace指令必须写在require块之后且路径需被Go正确解析；直接修改require行无效，应保留原require并添加replace映射；分叉无tag时需用伪版本或删require仅留replace；GOPROXY=direct才生效；replace仅为本地过渡方案，提交前须清理。
replace 指令必须写在 require 块之后，且路径要能被 Go 正确解析
直接改 go.mod 中的 require 行指向分叉仓库地址（比如把 github.com/original/repo 改成 github.com/yourname/repo）是无效的——Go 不会自动重写 import 路径，编译时仍会按原 import path 查找代码，而你本地没这个路径的模块。
正确做法是保留原 require 条目，再加 replace 映射：
-
replace必须放在require块之后、exclude或retract之前 - 右侧路径必须是合法模块根目录（含有效的
go.mod文件，且其中module声明与左侧一致） - 推荐用相对路径（如
../forked-repo），避免 CI 中因工作目录不同导致解析失败 - 如果 fork 在 GitHub 上但尚未打 tag，Go 默认拉取
master或main分支最新 commit；此时require中版本号可写成v0.0.0-yyyymmddhhmmss-commit格式（用go mod edit -require手动设），否则go mod tidy可能报错
分叉仓库未发布版本时，require 版本号怎么填才不报错
go mod tidy 会校验 require 中的版本是否存在远程仓库。如果你的分叉还没打任何 tag，Go 无法识别 v1.2.3 这类语义化版本。
这时有两个选择：
- 用伪版本（pseudo-version）：执行
go mod edit -require=github.com/yourname/repo@v0.0.0-00000000000000-000000000000占位，再配replace；go mod tidy会自动修正为实际 commit 时间戳格式 - 干脆删掉
require行，只留replace——Go 允许这样做，只要该模块被代码 import 了，go mod tidy就会补上带伪版本的require - 注意：不要写
v0.0.0，Go 会把它当正式版本去远端查，必然失败
GOPROXY=direct 时 replace 才真正生效
默认 GOPROXY（如 https://proxy.golang.org）会跳过 replace，优先走代理下载原模块。结果就是：你写了 replace，go build 却仍从原始仓库拉代码，本地修改完全没生效。
开发阶段务必设置：
-
export GOPROXY=direct（Linux/macOS）或set GOPROXY=direct（Windows） - 或者临时加参数：
go build -mod=mod（强制读取go.mod并应用replace） - CI 构建前记得还原
GOPROXY，否则可能漏掉依赖校验
提交前必须清理 replace，否则别人 clone 就构建失败
replace 是纯本地开发手段，路径对别人机器无效。如果忘记删，同事 git clone 后执行 go build 会直接报 cannot find module providing package ——因为 ../forked-repo 在他机器上根本不存在。
安全做法：
- 把
replace行加 Git 注释标记，比如// replace github.com/original/repo => ../forked-repo # dev-only，提醒自己别提交 - CI 脚本开头加
go mod edit -dropreplace=github.com/original/repo自动清理 - 更稳妥的是：分叉后立刻打一个临时 tag（如
v1.2.3-fork.1），然后require指向它，彻底不用replace
真正的麻烦不在怎么引用，而在怎么让别人不用改一行代码就能复现你的构建——replace 天然破坏可重现性，所以它永远只是过渡方案，不是终态。
