Go modules 怎样用 replace 调试本地依赖

在主项目的 go.mod 中保留依赖的 require，再用 replace 模块路径 => 本地模块目录 替换源码来源，就能联调尚未发布的依赖改动。import 仍使用原模块路径；右侧指向含 go.mod 的模块根目录，不是某个包目录。本地调试完成后撤销临时替换，CI 应使用团队明确管理的依赖来源。

官方文档地址：https://go.dev/ref/mod。下面的 example.com 模块名与 v0.0.0 都是自建示例，不是可下载产品或真实发布版本。命令供读者复现，本文不宣称已经执行或测试通过。

先明确本地联调和云端构建的不同目标

设想订单服务 order-api 正在调用 pricekit。开发者希望修改依赖函数，立刻由主服务调用，而不想每次都推送提交、发布标签再下载。此时主要约束是快速联调、目录可访问和变更可撤销；不是线上请求吞吐量。replace 改变依赖源码来源，并不会自动让运行中的服务热更新，修改后仍需重新构建或重启调试进程。

云端构建的目标不同：构建节点通常只拉取服务仓库，既没有开发机的兄弟目录，也没有未提交的依赖修改。一个本地成功的替换配置，不能证明交付环境可复现。方案选择需要同时考虑开发效率、源码可追踪性、CI 目录契约与维护成本。

确认主模块、模块根目录与版本范围

主模块是当前命令所处模块；replace 放在依赖模块自己的 go.mod 中，不会作为依赖自动传递给使用者。本地替换目标必须含 go.mod。本例主模块位于 order-api，依赖模块位于其兄弟目录 pricekit，所以从 order-api/go.mod 看，替换路径是 ../pricekit。编辑器打开哪个目录，不是命令实际处于哪个模块的可靠证据。

左侧不带版本会匹配该模块的所有版本；带版本则只匹配那个版本。右侧是本地目录时不带版本，版本约束仍由依赖图中的 require 表达。只有 replace 而没有相应依赖需求，不会凭空把模块加入依赖图。为了减少排障变量，本例让依赖 go.mod 的 module 声明与被替换模块路径一致。

图中“主项目”分组包含 order-api、require 与 replace；“本地依赖”分组包含 pricekit 和依赖 go.mod。order-api 与 require/replace 是配置所属关系，require 与 pricekit 是逻辑依赖关系，replace 与 pricekit 是内容来源映射，pricekit 与依赖 go.mod 是模块根声明关系。

在 replace、工作区与远程版本之间选择

只有单个项目临时试验时，replace 直观且可撤销；多模块长期联调可以评估工作区，不必让每个模块都维护兄弟路径。对外发布时优先记录可获取的固定版本，而不是依赖开发者未提交的文件。这里的取舍是工程建议，不能把任一方案当成所有项目的通用标准。

已有 go.work 时，先明确它是否参与命令解析。工作区可包含多个主模块及自己的 replace；冲突和覆盖可能导致实际来源与单个 go.mod 的直觉不同。为学习本例，可以在命令级设置 GOWORK=off，避免修改全局环境。

把依赖内容切换到本地目录

准备两个兄弟目录，order-api 放 go.mod 和 main.go，pricekit 放 go.mod 和 label.go。两个 go.mod 分别如下，go 1.22 是示例最低语言声明，不是最新版本推荐：

// order-api/go.mod：主模块声明逻辑依赖及本地替换。
module example.com/order-api

go 1.22

// 此版本为示例占位，不表示真实远程发布。
require example.com/pricekit v0.0.0

// 相对路径以本文件所在模块目录为基准，右侧不写版本。
replace example.com/pricekit => ../pricekit

// pricekit/go.mod：本地替换目标必须是模块根目录。
module example.com/pricekit

go 1.22

依赖中的 label.go：

package pricekit

import "strings"

// Label 给联调提供一个容易观察的原创行为入口。
func Label(name string) string {
    return "local:" + strings.TrimSpace(name)
}

主项目的 main.go：

package main

import (
    "fmt"
    "example.com/pricekit"
)

// 导入路径保持模块身份，不改成磁盘目录。
func main() {
    fmt.Println(pricekit.Label("  order-A  "))
}

注意 main.go 导入的是 example.com/pricekit，而不是 ../pricekit。replace 不要求把每个 import 改成本地路径，它在模块层面替换内容。下面命令都从 order-api 目录执行；已有项目使用其实际模块路径和原有 require，不要盲目覆盖为示例占位版本：

# 添加适用于该模块所有版本的本地替换，不修改 import。
go mod edit -replace=example.com/pricekit=../pricekit
# 隔离工作区配置，查看模块来源与替换信息。
GOWORK=off go list -m -json example.com/pricekit
# 在同一解析范围内重新运行主项目观察行为。
GOWORK=off go run .

读者应检查 JSON 中的 Replace.Path 与目录信息是否指向预期本地模块；Dir 是当前环境的真实路径，不应复制进文章或公共配置。按示例代码推导，Label 会去掉两侧空格并添加 local: 前缀，这不是本文实际运行日志。若调试断点仍落在另一份源码，先看模块解析范围与来源，不要首先删除整个模块缓存。

防止临时路径进入 CI 与交付环境

主 go.mod、替换目录、本地改动、CI 检出与远程版本是需要一起考虑的五个对象。“开发机”分组含替换目录与本地改动；“交付配置”分组含主 go.mod、CI 检出与远程版本。主 go.mod 与替换目录有配置依赖，替换目录包含本地改动；CI 检出需要明确提供 go.mod 所引用源码，远程版本则为交付提供可追踪来源。这些依赖不意味着 CI 自动拥有本地目录。

相对路径也可能出错：如果构建只复制 order-api 到容器，../pricekit 仍然不存在。绝对路径更难移植，但把它换成相对路径并不会自动解决源码缺失。团队若确实在 CI 使用本地 replace，需要显式检出两个仓库、固定提交、保持目录布局，并记录这个有意设计的构建契约。

其次，替换目标自己的 go.mod 会影响依赖图。仅改一行 replace 不保证其他依赖完全不变；需要理解 tidy 等命令可能调整 go.mod/go.sum。不要把本地源码替换理解为已通过远程校验和机制固定了内容，也不要对私有仓库一概关闭校验或代理规则来解决目录错误。

撤销替换并保留可复现依赖

对本例不带左侧版本的替换，用下列命令移除。若实际项目写的是带版本替换，就用相应 @version 移除；移除其中一条不代表其他替换也消失。

# 移除本例无左侧版本的临时替换。
go mod edit -dropreplace=example.com/pricekit
# 查看配置差异，保留用户或团队原有的其他修改。
git diff -- go.mod go.sum

撤销后，示例 v0.0.0 不能被当成已经发布的可获取版本。真实项目需要恢复原先可用的 require，或采用团队实际发布的新版本，再在正常构建环境中检查。不要自动删除 go.sum，不要用强制重置覆盖其他人的依赖修改。

• 主模块路径和本地依赖的 module 身份明确。
• 替换路径指向模块根，右侧不混入版本。
• 左侧带不带版本与本次联调范围一致。
• 实际构建是否使用工作区已明确。
• 临时路径没有无意进入 CI、容器和交付配置。
• 依赖改动已成为可追踪版本后，再撤销本地替换。

为什么只有 replace 还提示缺少依赖？因为映射源码来源不等于建立模块需求，应检查 require 与实际导入。

为什么修改依赖后服务行为没变？确认调用命令对应主模块、工作区范围和模块来源，再重新构建或运行；replace 本身不是热更新器。

发布库后使用者会继承这个 replace 吗？不会把依赖 go.mod 中的替换作为使用者主模块的替换传递。联调配置应由构建入口管理。

技术规则与命令参数参考 https://go.dev/ref/mod#go-mod-file-replace、https://go.dev/ref/mod#go-mod-edit；工作区规则参考同一官方手册的 go.work 部分。示例模块与代码为原创，目录关系用于解释本地联调，不代表线上仓库。