Go项目无需强制设pkg目录，仅当提供需语义化版本、对外暴露稳定API的可复用库（如SDK）且有独立go.mod时才适用；pkg与internal职责不同，前者供外部导入并受兼容性约束，后者为模块内私有代码；主流大型项目多通过多模块拆分而非pkg实现解耦。
Go 项目里要不要设 pkg 目录，取决于你是否在提供可复用的库代码——不是所有项目都需要它，硬加反而破坏 Go 的默认组织逻辑。
什么时候该建 pkg 目录
Go 官方推荐按「功能边界」而非「代码类型」划分目录，pkg 只在明确对外暴露稳定 API 时才有意义。比如你正在开发一个会被其他项目 go get 引入的 SDK、工具包或中间件组件。
- 你的模块有独立
go.mod，且版本号受控（如v1.2.0） - 外部项目通过
import "github.com/you/repo/pkg/xxx"显式引用，而不是直接 import 主模块下的子目录 - 你希望把内部实现（
internal/）和公共接口（pkg/）物理隔离，避免误导用户依赖未承诺的符号
pkg 和 internal 的分工容易搞混
pkg 不是 internal 的镜像，也不是“放工具函数的地方”。它的存在前提是：这些代码被设计成可单独维护、有语义化版本、接受外部兼容性约束。
-
internal/是 Go 内置的访问控制机制，任何在internal/下的包，只有同一模块根路径下的代码能 import —— 它不对外，也不需要版本承诺 -
pkg/下的包必须能被外部模块 import，因此要经得起go list -json扫描、gopls跳转、go doc生成文档 - 常见错误：把数据库封装、HTTP 客户端之类本该属于主模块业务逻辑的代码塞进
pkg，结果导致版本升级时不敢动，又不敢不维护
社区主流项目其实很少用 pkg
看 Kubernetes、Docker、Terraform 这些大型 Go 项目源码，你会发现它们多数不用 pkg 目录。它们靠的是清晰的模块拆分（多个 go.mod）+ 合理的 internal/ 划界 + 主模块下直接暴露顶层 API。
立即学习“go语言免费学习笔记（深入）”；
- 如果你的项目是 CLI 工具或服务程序（如
prometheus），API 入口就是main.go，其余都是支撑逻辑，根本不需要pkg - 如果你拆了多个 module（比如
github.com/you/core和github.com/you/cli），每个 module 自己就是“包”，无需再套一层pkg - 强行模仿某些老项目用
pkg，可能只是复制了表层结构，却没继承其版本管理和发布流程，结果变成“假公共包”
真正难的不是建不建 pkg，而是判断哪些代码值得承诺兼容性——这得看调用方是谁、升级成本多高、有没有配套的测试和 changelog。一旦放进 pkg，删函数、改签名、甚至重命名都得走 v2 分支，不是改个 go.mod 就完事的。
