Go · Modules 与构建发布

场景 1 · 私有仓拉取: GOPRIVATE + insteadOf 重写

go get 私仓报 404 或 checksum mismatch, 九成是走了公网代理; 本地走 ssh, CI 走 token:

go env -w GOPRIVATE=corp.example.com/*
go env -w GONOSUMDB=corp.example.com/*
go env GOPRIVATE
git config --global \
  url."git@corp.example.com:".insteadOf "https://corp.example.com/"
go mod tidy
go build ./...

CI 上把 insteadOf 换成 url."https://oauth2:${GIT_TOKEN}@corp.example.com/" 即可用 token 拉取; GOPRIVATE 同时解决了"私仓路径被送去公网 sumdb 校验"的信息泄露。

场景 2 · replace 指向本地路径联调共享库

authlib 改一行就要发版半天; 联调期用 replace 直连工作区副本:

module corp.example.com/gateway

go 1.23

require corp.example.com/authlib v0.4.1

replace corp.example.com/authlib => ../authlib

网关立刻用上本地未发布的 authlib; 联调完删掉这行再 tidy —— 或者干脆用场景 9 的 go.work, 更干净。

场景 3 · 版本号注入构建信息

线上排查第一个问题永远是"这二进制是哪个版本"; 链接期注入 + 构建信息兜底:

var version = "dev"
func main() {
    if bi, ok := debug.ReadBuildInfo()(); ok && bi.Main.Version != "(devel)" {
        version = bi.Main.Version              // go install mod@v 时自动有版本
    }
    fmt.Printf("gateway %s (go %s)\n", version, runtime.Version())
}
// go build -ldflags "-X main.version=1.47.2" 注入生效
// -X 只认 string; 路径必须 包名.变量名, 大小写敏感

场景 4 · 多阶段 Dockerfile: builder → scratch 20MB 内

单阶段把整个 GOPATH 打进镜像动辄 1GB; 分层构建 + 静态编译一步到位:

FROM golang:1.23-alpine AS builder
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 go build -trimpath \
    -ldflags "-s -w -X main.version=1.47.2" \
    -o /out/gateway ./cmd/gateway
FROM scratch
COPY --from=builder /out/gateway /gateway
COPY --from=builder /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/
ENTRYPOINT ["/gateway"]

要点: go.mod/go.sum 先拷、源码后拷, 依赖层命中缓存重建只要 8s; scratch 里必须带上 ca-certificates 否则 HTTPS 全挂; 镜像从 1.1GB 降到 11MB。

场景 5 · 交叉编译发布矩阵: 5 平台一个脚本

Go 的招牌能力, 打 tag 即出全平台产物与校验和:

set -euo pipefail
VER=${GITHUB_REF##*/tags/}
for target in linux/amd64 linux/arm64 darwin/amd64 darwin/arm64 windows/amd64; do
  GOOS=${target%/*}; GOARCH=${target#*/}
  CGO_ENABLED=0 go build -trimpath \
    -ldflags "-s -w -X main.version=$VER" \
    -o "dist/gateway-${GOOS}-${GOARCH}" ./cmd/gateway
  tar -czf "dist/gateway-${GOOS}-${GOARCH}.tgz" -C dist "gateway-${GOOS}-${GOARCH}"
done
sha256sum dist/* > dist/checksums.txt

场景 6 · go mod tidy 进 CI: 防依赖"顺手漂移"

有人手动改 go.mod 加依赖忘了 tidy, 或升级没锁版本, 下次构建全体遭殃; PR 门禁直接拦:

name: mod-hygiene
on: [pull_request]
jobs:
  tidy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-go@v5
        with: { go-version: '1.23' }
      - run: go mod tidy
      - run: git diff --exit-code go.mod go.sum

tidy 后 git diff 非空就说明提交者忘了同步 —— 门禁用差异说话, 比 code review 盯着看可靠。

场景 7 · govulncheck 周扫依赖出工单

依赖漏洞是长期债, 每周一扫, 按真实调用路径降噪:

name: vuln-scan
on:
  schedule: [{ cron: '0 3 * * 1' }]
jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-go@v5
        with: { go-version: '1.23' }
      - run: go install golang.org/x/vuln/cmd/govulncheck@latest
      - run: govulncheck ./...

govulncheck 只报"你的代码真的调用了漏洞符号"的项, 比纯版本号匹配少 90% 噪音; 扫出高危按工单升级。

场景 8 · vendor 模式: 内网构建机拉不到代理

金融内网构建机不允许出公网, GOPROXY 全被防火墙拦; 冻结一份依赖副本进仓库:

go mod verify
go mod vendor
go build -mod=vendor ./...
du -sh vendor/
git add vendor go.mod go.sum
git commit -m "vendor: freeze deps for intranet builder"

构建时 -mod=vendor 强制从 vendor/ 读依赖, 完全不碰网络; 代价是每次升依赖要重新 vendor 并提交一个巨型 diff, 适合强隔离环境。

场景 9 · go.work: 三服务本地联调不污染 go.mod

网关、authlib、billing 三个仓库联动改 bug, 反复发版太痛; workspace 一文件圈住:

go 1.23

use (
    ./gateway
    ./authlib
    ./billing
)

目录下 go build 自动把三个模块互相解析成本地代码, go.mod 一个字不用改; 团队约定 go.work 提交与否要统一, 别一半人有一半人没有。

场景 10 · 二进制 28MB 瘦到 9MB: 追查谁带进来的巨包

产物莫名巨大, 先问依赖图"这条边是谁画的":

go mod graph | wc -l
go mod graph | grep ' golang.org/x/text@' | sort -u
go mod why -m golang.org/x/text
go list -m all | wc -l
go list -deps ./... | wc -l
go version -m dist/gateway
du -h dist/gateway

go mod why 打印出引入链: gateway/ui → x/text/encoding —— 是 UI 库为一个小函数拖进全家桶; 换成轻量实现后依赖数从 147 降到 89, 二进制 28MB → 9MB。