go mod replace 是本地开发私有模块的直接方案，需严格匹配模块名与路径，执行后须 go mod tidy；Athens 代理缓存私有模块，需配置下载模式与 GOPRIVATE；打 tag 需含 go.mod 且以 v 开头；go.work 用于多模块协同开发，不提交至 CI。
用 go mod replace 替换本地开发中的私有模块
当多个项目共用一个内部模块，又需要边改边测时，go mod replace 是最直接的方案。它绕过远程拉取，强制将模块路径映射到本地文件系统路径。
常见错误是写错替换路径：左边必须和 go.mod 中 require 的模块名完全一致（包括版本号），右边必须是绝对路径或相对于当前 go.mod 的相对路径。
- 在主项目根目录执行
go mod edit -replace github.com/your-org/utils=../utils - 若
../utils下没有go.mod，go build会报no required module provides package - 替换后需运行
go mod tidy，否则go list -m all仍显示旧版本 - 该替换仅作用于当前模块，不传递给下游依赖（除非下游也显式 replace）
搭建最小可用的私有 Go 代理服务（Athens）
不用自建完整私有仓库，用 athens 就能缓存和代理私有模块。它不托管源码，只缓存已发布的 vX.Y.Z 版本，适合已有 GitLab/GitHub 私有库的团队。
关键配置点在于 ATHENS_DOWNLOAD_MODE 和 ATHENS_GO_BINARY_ENV_VARS：前者决定是否允许从 VCS 直接下载（设为 sync 更安全），后者可注入公司内网 Git 认证凭据。
立即学习“go语言免费学习笔记（深入）”；
- 启动命令示例：
docker run -d -p 3000:3000 \ -e ATHENS_DOWNLOAD_MODE=sync \ -e ATHENS_GO_BINARY_ENV_VARS='GOPRIVATE=github.com/your-org' \ -v $(pwd)/storage:/var/lib/athens \ --name athens-proxy \ gomods/athens:v0.18.0
- 客户端需设置：
go env -w GOPROXY=http://localhost:3000,direct -
GOPRIVATE必须包含所有私有模块前缀，否则go工具链会跳过代理、直连 GitHub 并失败
私有模块打 tag 的实际约束条件
Go 模块版本不是字符串任意写，v1.2.3 这类语义化标签必须真实存在于 Git 远程分支上，且对应 commit 的根目录下必须有 go.mod 文件——否则 go get 会报 invalid version 或 unknown revision。
- 打 tag 前确认：
git checkout main && go mod tidy && git add go.mod go.sum && git commit -m "mod: update deps" - tag 名必须以
v开头（如v0.4.1），不能是0.4.1或release/v0.4.1 - 推送命令必须带
--tags：git push origin v0.4.1或git push origin --tags - 若模块路径含子目录（如
github.com/your-org/libs/auth），tag 应打在仓库根，而非子目录下
go.work 在多模块协同开发中的真实用途
go.work 不是替代 go.mod，而是解决「同时改 A、B、C 三个模块，且它们互相 import」的临时开发场景。它让 go 命令把多个独立模块当作一个工作区看待。
容易被忽略的是：它只影响当前目录及子目录下的 go 命令行为；一旦 cd 到某个子模块单独运行 go build，就退回到单模块模式。
- 生成方式：
go work init ./module-a ./module-b ./module-c - 添加新模块：
go work use ./new-module - 如果某个模块未在
go.work中声明，但被其他模块require，go run仍会尝试从 proxy 下载——不会自动 fallback 到本地路径 -
go.work文件本身不提交到 CI，仅用于开发者本地联调
replace 临时改完忘了删，导致上线构建拉到线上环境的仍是旧版；或者 go.work 提交进 repo，CI 因缺少本地路径直接失败。这些都不是技术限制，是协作边界没划清。 
