应使用 replace 指令在 go.mod 中将远程模块映射为本地相对路径，如 replace github.com/user/mylib => ../mylib，要求本地路径存在有效 go.mod，且仅限开发阶段使用，提交前必须删除。

用 replace 指令重定向本地模块路径

Go Modules 默认从远程仓库拉取依赖，但开发中常需测试尚未发布的本地模块。直接改 import 路径或软链接不可靠，正确做法是在主模块的 go.mod 中添加 replace 指令。

假设你有主项目 myapp，想临时使用本地路径 ../mylib 替换模块 github.com/user/mylib：

module myapp

go 1.21

require (
    github.com/user/mylib v0.1.0
)

replace github.com/user/mylib => ../mylib

注意：replace 后的本地路径必须是相对路径（相对于 go.mod 所在目录），且目标目录下必须存在有效的 go.mod 文件。

• 若本地模块无 go.mod，运行 go mod init github.com/user/mylib 初始化
• replace 只在当前模块生效，不会影响其他项目或 go get 行为
• 提交前应删掉 replace，否则 CI 或他人构建会失败

用 go mod edit -replace 安全修改依赖映射

手动编辑 go.mod 易出错，尤其涉及多版本或跨平台路径时。推荐用命令行工具动态管理：

go mod edit -replace github.com/user/mylib=../mylib

该命令会自动校验路径合法性，并更新 go.sum（如果需要）。若要撤销替换：

go mod edit -dropreplace github.com/user/mylib

• 执行后务必运行 go mod tidy，确保依赖图一致
• Windows 下路径分隔符用 /（Go 工具链统一处理，不建议用 \）
• 若提示 no matching versions，说明 require 行未声明对应模块，先 go get github.com/user/mylib@v0.1.0 占位

避免 file:// 协议或绝对路径

有人尝试用 replace github.com/user/mylib => file:///home/user/mylib 或 Windows 绝对路径，这会导致协作中断：

• 绝对路径无法被他人复现，go build 直接报错 cannot find module providing package
• file:// 协议虽语法合法，但 Go 1.18+ 已明确不鼓励，且某些代理或私有模块镜像会忽略它
• CI 环境通常无权访问开发者本地磁盘路径

真正可协作的方式只有两种：用相对路径 + replace（仅限开发阶段），或发布到私有 proxy / git 服务器后走标准 require。

本地模块的 go.mod 版本号不影响 replace 行为

很多人误以为本地模块的 module 声明必须和 require 中的路径完全一致，其实不然：

只要 replace 左侧与 require 中的模块路径相同，右侧本地目录里的 go.mod 可以写任意合法模块名（如 mylib/local），Go 构建时只认路径映射，不校验模块名一致性。

• 但强烈建议保持一致，否则 IDE（如 GoLand）可能无法正确跳转或补全
• 若本地模块被多个项目 replace，它的 go.mod 中 module 名最好固定，避免混淆
• go list -m all 会显示本地路径而非模块名，这是正常现象

本地路径依赖本质是开发期的“临时打桩”，不是长期方案。上线前务必确认所有 replace 已清理，且远程模块版本已发布并验证兼容性。