2.2 升级、replace 与私有模块
上一节讲的是「版本被谁抬高了」这类被动问题。本节讲主动操作：我想升级依赖、我想临时用某个 fork、我的私有仓库拉不下来。
这三件事分别对应 go get 的升级参数、replace 指令、以及 GOPRIVATE 系列环境变量。
本节实测
go list -u、go get -u、go get -u=patch三种升级粒度的差异，演示replace把依赖指向本地目录的完整流程，并厘清GOPRIVATE对GONOPROXY、GONOSUMDB的联动。
2.2.1 先看有什么可升
升级之前先列清单。go list -u -m all 会列出每个模块的当前版本和可用最新版本（方括号里）：
$ GOTOOLCHAIN=go1.27.0 GOPROXY=https://goproxy.cn,direct go list -u -m all
example.com/updemo
golang.org/x/mod v0.8.0 [v0.42.0]
golang.org/x/sys v0.5.0 [v0.49.0]
golang.org/x/text v0.14.0 [v0.43.0]
golang.org/x/tools v0.6.0 [v0.51.0]
读法：v0.14.0 [v0.43.0] 表示当前用 v0.14.0，最新是 v0.43.0。没有方括号的行表示已经是最新（或没有更新）。注意 -m all 会把间接依赖也一并列出，上面只保留了直接依赖那几行，完整输出会很长。
只想看直接依赖的更新，可以用 -f 过滤掉标了 Indirect 的模块：
$ GOTOOLCHAIN=go1.27.0 go list -u -m -f '{{if not .Indirect}}{{.Path}} {{.Version}}{{end}}' all
2.2.2 三种升级粒度
go get 的升级有明确的粒度控制：
| 命令 | 升级范围 | 语义 |
|---|---|---|
go get -u=patch | 只升到最新的补丁版本 | v1.2.3 → v1.2.9 |
go get -u | 升到最新的次版本（含补丁） | v1.2.3 → v1.5.0 |
go get module@latest | 升到该模块最新版（可跨主版本） | v1.2.3 → v2.0.0 |
go get module@v1.4.2 | 精确指定版本 | 无 |
实测 -u=patch 的效果：
$ GOTOOLCHAIN=go1.27.0 GOPROXY=https://goproxy.cn,direct go get -u=patch
$ GOTOOLCHAIN=go1.27.0 go list -m golang.org/x/text
golang.org/x/text v0.14.0
没有任何变化。原因是 x/text 的 v0.14 这条线上只有 v0.14.0 一个版本，没有更新的补丁：
$ GOTOOLCHAIN=go1.27.0 go list -m -versions golang.org/x/text | tr ' ' '\n' | grep '^v0\.14'
v0.14.0
换 -u（允许跨次版本）：
$ GOTOOLCHAIN=go1.27.0 GOPROXY=https://goproxy.cn,direct go get -u
go: upgraded golang.org/x/text v0.14.0 => v0.43.0
$ GOTOOLCHAIN=go1.27.0 go list -m golang.org/x/text
golang.org/x/text v0.43.0
一口气从 v0.14.0 跳到 v0.43.0。这就是 -u 的危险之处：它可能带来几十个次版本的累积变更。生产项目里更稳的做法是一次只升一个模块，看完它的 changelog 再决定：
$ GOTOOLCHAIN=go1.27.0 GOPROXY=https://goproxy.cn,direct \
go get golang.org/x/text@v0.20.0
2.2.3 升级的纪律
TaskHub 的依赖升级遵循三条纪律：
- 一次一个模块。多个模块一起升，出问题时无法二分定位。
- 升完立刻跑测试，尤其是集成测试。编译通过不代表行为不变。
- 升完看
git diff go.mod，确认没有连带升级别的模块（见 2.1.4）。
把这三条固化成脚本：
#!/usr/bin/env bash
set -euo pipefail
mod="$1"; ver="$2"
GOTOOLCHAIN=go1.27.0 GOPROXY=https://goproxy.cn,direct go get "${mod}@${ver}"
GOTOOLCHAIN=go1.27.0 go mod tidy
git diff --stat go.mod go.sum
GOTOOLCHAIN=go1.27.0 go build all
GOTOOLCHAIN=go1.27.0 go test all
2.2.4 replace 的三种用法
replace 把某个模块的解析目标改掉。它有三种典型用法：
| 用法 | 写法 | 场景 |
|---|---|---|
| 指向本地目录 | replace m => ./local | 多模块联调 |
| 指向 fork | replace m => github.com/me/m v1.2.3 | 用未合并的修复 |
| 版本重定向 | replace m v1.0.0 => m v1.0.1 | 跳过有问题的版本 |
指向本地目录是最常用的。实测给 api 模块加一条：
$ cd api
$ GOTOOLCHAIN=go1.27.0 go mod edit -replace=github.com/google/uuid=/tmp/gbwork/localuuid
$ cat go.mod
module example.com/taskhub/api
go 1.27.0
require (
github.com/google/uuid v1.6.0 // indirect
golang.org/x/text v0.20.0 // indirect
)
replace github.com/google/uuid => /tmp/gbwork/localuuid
go list -m 会显示替换后的目标：
$ cd .. && GOTOOLCHAIN=go1.27.0 go list -m github.com/google/uuid
github.com/google/uuid v1.6.0 => /tmp/gbwork/localuuid
=> 后面就是实际使用的路径。本地目录的内容随文件系统变化，所以本地 replace 不会在 go.sum 里留下条目——哈希对目录没有意义。
2.2.5 replace 的提交陷阱
replace 指向本地目录时，这个路径只在你本机存在。如果把这样的 go.mod 提交上去，同事 clone 后会直接构建失败：
go: /tmp/gbwork/localuuid: no such file or directory
纪律：本地 replace 只能存在于未提交的工作区里。真要用 fork，得指向一个可访问的仓库地址：
$ GOTOOLCHAIN=go1.27.0 go mod edit \
-replace=github.com/foo/lib=github.com/me/lib@v1.2.3
指向 fork 的 replace 会写进 go.sum（因为是真实的模块版本），可以安全提交。但更干净的做法是推动上游合并，让 replace 最终消失。
2.2.6 私有模块为什么拉不下来
默认情况下，go 会把所有模块路径当公共模块处理：先查代理，再查 sumdb。公司内网的 gitlab.com/acme/internal-lib 既不在公共代理上，也不在 sumdb 里，于是报错：
$ GOTOOLCHAIN=go1.27.0 GOPROXY=off go get gitlab.com/acme/internal-lib@latest
go: gitlab.com/acme/internal-lib@latest: module lookup disabled by GOPROXY=off
（这里用 GOPROXY=off 是为了复现得确定，真实环境会先尝试代理再走直连。）
解法是告诉 go：这些路径是私有的，别走公共代理，也别查 sumdb。
2.2.7 GOPRIVATE 三件套
核心变量是 GOPRIVATE，它接受逗号分隔的路径前缀：
$ GOPRIVATE=gitlab.com/acme/* go env GOPRIVATE GONOPROXY GONOSUMDB
gitlab.com/acme/*
gitlab.com/acme/*
gitlab.com/acme/*
关键行为：设置 GOPRIVATE 会自动把 GONOPROXY 和 GONOSUMDB 设成同一个值（如果它们没被单独设置）。三者分工：
| 变量 | 作用 | 默认来源 |
|---|---|---|
GOPRIVATE | 总开关，同时影响下面两个 | 空 |
GONOPROXY | 匹配的模块不走 GOPROXY，直接 direct | 继承 GOPRIVATE |
GONOSUMDB | 匹配的模块不查校验和数据库 | 继承 GOPRIVATE |
实际配置里，通常只设 GOPRIVATE 就够了：
$ GOTOOLCHAIN=go1.27.0 go env -w GOPRIVATE=gitlab.com/acme/*,github.com/acme/*
go env -w 会把配置写进 go env 的持久化文件，对之后所有命令生效。
2.2.8 私有模块的认证
GOPRIVATE 只解决「走哪条路」，不解决「怎么证明你是你」。私有仓库的认证有几种方式：
| 方式 | 配置 | 适用 |
|---|---|---|
| SSH | git config url."git@gitlab.com:".insteadOf "https://gitlab.com/" | 已有 SSH key |
.netrc | 在 ~/.netrc 写 machine/login/password | HTTPS + token |
GIT_ASKPASS | 指向一个返回 token 的脚本 | CI 环境 |
CI 里最常见的是把 token 放进环境变量，再让 git 用它：
$ git config --global url."https://oauth2:${GITLAB_TOKEN}@gitlab.com/".insteadOf "https://gitlab.com/"
注意不要把 token 写进 go.mod 或提交进仓库——它只该出现在 CI 的加密变量里。
2.2.9 GOINSECURE：什么时候才该用
如果私有仓库只有 HTTP（没有 HTTPS），需要 GOINSECURE：
$ GOINSECURE=gitlab.internal go env GOINSECURE
gitlab.internal
GOINSECURE 允许对匹配的模块使用不安全的 HTTP 连接。它的适用场景极窄——只用于完全隔离的内网。公网模块绝对不要加进 GOINSECURE，那等于关掉了中间人攻击的防护。
| 变量 | 关掉的是 | 风险 |
|---|---|---|
GOPRIVATE | 代理 + sumdb | 低（私有模块本来就不该走公共设施） |
GOINSECURE | TLS 校验 | 高（可能被中间人替换） |
GONOSUMDB | 校验和数据库 | 中（失去防篡改背书） |
2.2.10 完整配置示例
把 TaskHub 的私有模块配置整理成一份 go env -w 清单：
$ GOTOOLCHAIN=go1.27.0 go env -w \
GOPROXY=https://goproxy.cn,direct \
GOPRIVATE=gitlab.com/acme/*,github.com/acme/* \
GOFLAGS=-mod=mod
$ GOTOOLCHAIN=go1.27.0 go env GOPROXY GOPRIVATE GONOPROXY GONOSUMDB
https://goproxy.cn,direct
gitlab.com/acme/*,github.com/acme/*
gitlab.com/acme/*,github.com/acme/*
gitlab.com/acme/*,github.com/acme/*
GOPROXY 里的 ,direct 是兜底：代理找不到时直接拉。GOPRIVATE 匹配的模块会自动跳过代理，走 direct。
2.2.11 常见坑速查
| 现象 | 原因 | 处理 |
|---|---|---|
module lookup disabled by GOPROXY=off | 私有模块没配 GOPRIVATE | 配 GOPRIVATE 前缀 |
410 Gone / 404 拉私有模块 | 走了公共代理 | 确认路径被 GOPRIVATE 覆盖 |
同事构建失败 no such file | 提交了本地目录 replace | 移除本地 replace 或改指向仓库 |
-u=patch 没变化 | 该版本线没有更新补丁 | 正常，换 -u 或指定版本 |
| 升级后编译失败 | 跨次版本 API 变更 | 一次只升一个，看 changelog |
| token 泄露进 git 历史 | 把 token 写进 URL 提交 | 用 insteadOf 配在本地/CI |
到这里，依赖的「增删改查」你已经有了完整工具箱。但升级依赖时还有个绕不开的问题：新版本会不会引入已知漏洞？ 下一节用 govulncheck 把这个问题变成一条可执行的检查。
阅读导航：上一节：2.1 最小版本选择与冲突排查 · 下一节：2.3 供应链安全与 SBOM（govulncheck） 。
继续阅读
探索更多技术文章
浏览归档，发现更多关于系统设计、工具链和工程实践的内容。