replace必须写在go.mod末尾require块之后，格式为replace old/path => ./local/path，右侧须为相对路径且本地包go.mod中module名须与左侧完全一致；CI中失效主因是路径不存在，应改用临时tag版本替代本地路径。
go.mod 中的 replace 怎么写才不会在 CI 中失效
本地开发时用 replace 指向本地路径很常见，但 CI 构建失败往往就栽在这儿——replace 是开发期指令，只在模块感知模式下生效，且不参与 go.sum 锁定，更不会被远程构建环境识别。
- CI 环境默认不拉取本地文件系统路径，
replace github.com/org/lib => ../lib会直接报错cannot find module providing package -
replace不应出现在正式发布的go.mod中；它只该用于你本地调试，且必须配合// +build ignore或单独维护 dev.go.mod（非标准做法，易出错） - 真正可靠的做法是：把待调试的公共模块先打一个临时 tag（如
v0.1.0-dev.1），然后replace改成github.com/org/lib => github.com/org/lib v0.1.0-dev.1，再go mod tidy——这样 CI 能正常 fetch，本地也能快速切换 - 如果必须用文件路径，CI 脚本里得提前
cp -r ../lib ./vendor/github.com/org/lib并启用GOFLAGS="-mod=vendor"，但这绕过了模块机制，后续升级麻烦
pkg/ 目录下的公共模块怎么设计才能被安全复用
pkg/ 是 Go 项目中对外暴露能力的“门面”，但它不是随便放工具函数的地方。设计不当会导致循环导入、语义模糊、或被迫导出内部实现。
- 每个
pkg/xxx必须有明确职责边界，例如pkg/auth只处理鉴权逻辑，不掺杂 HTTP transport 或数据库细节 - 避免跨包强依赖：若
pkg/auth需要日志，应接受log.Logger接口作为参数，而不是直接 importpkg/log——否则pkg/log修改会影响所有使用者 - 导出名需体现稳定性：
func NewValidator() *Validator比func Validate(...)更利于未来扩展；结构体字段尽量小写（私有），通过方法暴露行为 - 测试必须覆盖公共 API 行为，而非实现细节；
pkg/auth的测试不应 mockinternal/db，而应构造真实输入输出断言
internal/ 和 pkg/ 的边界到底在哪
很多人把“想让别人用”就扔进 pkg/，“暂时不想给外人看”就塞 internal/，结果导致 pkg/ 膨胀成大杂烩，internal/ 里却藏着可复用的核心算法——这是对 Go 模块边界的误读。
-
internal/的限制是编译期强制的：任何路径含/internal/的包，都无法被模块路径之外的代码 import；它不是命名约定，而是 Go 工具链硬规则 -
pkg/不等于“所有公共代码”，而是“有意设计为独立消费单元”的包；比如pkg/httpcli应能单独go test、有自己 README、支持 semantic versioning - 真正的分界点在于发布意图：你是否愿意为这个包维护兼容性承诺？是否准备把它放到 GitHub 单独仓库？如果是，它就该是
pkg/；如果只是当前项目内多个子模块共用的胶水层，就该在internal/pkg/下 - 一个信号：当你发现
pkg/里的某个包频繁 require 当前项目的其他pkg/包（如pkg/authimportpkg/db），说明它还没准备好对外暴露，应退回internal/
如何让公共模块既能被当前项目用，又能独立发布
这不是“能不能”的问题，而是“要不要承担维护成本”的问题。Go Modules 允许你用同一份代码服务两种场景，但必须主动管理版本和导入路径。
立即学习“go语言免费学习笔记（深入）”；
- 第一步：把公共逻辑从
internal/抽到独立目录，比如../go-commons/auth，并初始化自己的go.mod（路径设为github.com/your-org/go-commons/auth） - 第二步：在主项目
go.mod中添加replace github.com/your-org/go-commons/auth => ../go-commons/auth，同时require github.com/your-org/go-commons/auth v0.0.0-00010101000000-000000000000（占位） - 第三步：每次发版前，在
go-commons/auth目录下git tag v1.2.0，然后回到主项目执行go get github.com/your-org/go-commons/auth@v1.2.0，自动更新require和go.sum - 关键细节：主项目
go.mod中的replace仅用于开发，CI 用的是require对应的真实版本；所以 commit 前务必确认replace是否已删或注释掉
pkg/ 时，能否清晰回答：它的接口契约是什么？谁负责它的演进节奏？有没有人会在另一个仓库里直接 import 它？这些问题没想清，目录再多也只是假模块。 
