Go workreplace 出错时怎么查CI 下载

Go 项目在本地能编译，到了 CI 却出现“找不到模块”“replacement directory does not exist”或依赖下载失败，先别急着删缓存。最常见的原因是 CI 没有启用预期的 go.work，或者 replace 的相对路径相对于另一份文件、另一层工作目录解析了。排查顺序应是：先确认工作区，再核对路径和模块名，最后才看代理与权限。

一句话判断：go.work 只在 Go 命令实际进入该工作区时生效；replace 只是改写已有模块的来源，单独写它不会把模块加入依赖图。

先确认 CI 实际使用了哪份 go.work

在构建前临时打印这组环境信息，重点看 GOWORK。它如果是 off，或者指向不存在的文件，工作区里的 use 与 replace 都不会按你的预期参与解析。

# 查看工作区、主模块和模块下载入口，先确认事实再改配置
go env GOWORK GOMOD GOPROXY GOPRIVATE

# 输出当前构建可见的模块及其最终版本来源
go list -m -json all

如果命令从仓库子目录启动，Go 会向上寻找工作区或模块文件；但 CI 常见的浅检出、改变工作目录、显式设置 GOWORK=off，都会让本地与 CI 走不同的解析路径。日志中至少应能看到预期的 go.work 路径和主模块。

核对 replace 的左边、右边和相对路径

replace 有三种容易混淆的写法：替换所有版本、只替换某个版本，以及替换到另一个模块版本或本地目录。指向本地目录时，右侧不能再写版本号；目录里还必须有 go.mod，其中的 module 通常要与被替换的模块路径对应。

// go.work：相对路径以 go.work 所在目录为参照
go 1.22

use (
    ./app
    ./libs/core
)

// 仅把已有依赖的来源切到仓库内的本地模块
replace example.com/core => ./libs/core

例如 go.work 在仓库根目录，./libs/core 就应当位于根目录下。若 CI 只检出了 app 子目录，或者工作目录里没有 libs/core/go.mod，就会报路径不存在。不要把路径改成“看起来能用”的绝对路径，因为那会把本机目录带进配置。

写了 replace 仍找不到模块，先查 require

下面的关系是关键：require 决定模块进入依赖图，replace 决定 Go 到哪里取它的内容。只有 replace 没有 require，Go 不一定会解析这条规则。

// go.mod：先声明依赖，再替换它的来源
module example.com/app

go 1.22

require example.com/core v0.0.0-replace

replace example.com/core v0.0.0-replace => ../libs/core

这里的伪版本只是为了给本地替换提供一个稳定的依赖坐标，实际项目也可以使用已有版本。若改成另一个模块路径，导入语句仍应使用原模块的包路径；只要替换模块的 go.mod 能匹配该路径，Go 会在解析阶段切换来源。

本地成功、CI 下载失败时的四项对照

把本地和 CI 的以下项目并排比较，通常比反复执行 go clean -modcache 更快：

• 文件是否完整：go.work 引用的每个目录都已检出，并且目录内有正确的 go.mod。
• 执行位置是否一致：CI 是否从工作区根目录启动，是否设置了 GOWORK=off。
• 下载策略是否一致：公开依赖看 GOPROXY，私有模块还要核对 GOPRIVATE、凭据和网络权限。
• 最终解析是否一致：用 go list -m -json all 查看 Replace 字段，而不是只看 go.mod 的文本。

修复后可以在仓库根目录运行 go work use -r . 整理工作区，再用 go work sync 将工作区依赖版本同步回各主模块。若这套本地替换只服务开发联调，发布前应移除临时规则并改用已发布版本；若 CI 也依赖本地模块，就必须把完整目录和 go.work 一起交付。

几个容易误判的情况

只改 GOPROXY：它解决的是模块下载入口，不能修复缺失的本地 replacement 目录。

只运行 go mod tidy：它不能替你决定 CI 是否进入工作区，也不会把错误的相对路径变正确。

把 go.work 当成发布依赖：工作区适合多模块同时开发；正式版本仍应让模块在工作区外也能按版本解析。

相关问题

为什么本地 go run 正常，CI 却提示 module not found？优先检查 CI 的 GOWORK、启动目录和检出内容，再检查代理。

replace 右侧本地目录能写绝对路径吗？技术上可以指向本机路径，但不适合提交到团队配置；应使用相对于 go.work 或 go.mod 的可复现路径。

什么时候应该不用 go.work？如果模块已经发布且只需按版本消费，去掉临时工作区替换，让 CI 验证真实的版本依赖更稳妥。

资料依据：Go 官方的 go.work 工作区教程与 Go Modules Reference，说明 use、replace、模块解析和 go work sync 的关系。