空包是编译期契约而非占位符，指仅含doc.go且无导出符号的包，用于确保import路径存在但禁止引用内部符号；必须有.go文件，不触发init，支持go:embed/go:generate及go doc。
空包不是占位符，是编译期契约
Go 里没有“空包”这个语言概念，package main 或 package utils 只要目录下有 .go 文件、且文件里有合法的 package xxx 声明，就构成一个包。所谓“空包”，通常指只含一个 doc.go 文件、不导出任何符号的包——它不是语法糖，而是开发者主动建立的编译期约束。
它的核心用途只有一个：让 import 路径存在，但禁止直接引用内部符号。比如 import "myproj/internal/log" 能通过编译，但你写 log.Debug() 会报错：未定义 log。因为 log 包没导出任何东西。
常见错误现象：
– 误以为加个空 doc.go 就能“占位”防止别人删目录 → 实际上只要路径被 import，Go build 就会检查该路径是否存在、是否可解析；
– 把空包当模块边界用，结果发现 go list -f '{{.Deps}}' ./... 仍把空包列为依赖 → 它只是没导出符号，不是不存在。
- 空包必须至少有一个
.go文件（哪怕只有package log和注释）；否则go build会报no Go files in ... -
doc.go里可以写// Package log provides logging infrastructure.，但不能写func Debug(...)或var DefaultLogger *Logger - 如果想彻底隔离，应该用
internal/目录，而不是靠“空”来防滥用
为什么不用 _ import 而要用空包
有人觉得 import _ "myproj/migration" 更轻量，但这是两回事：_ 是触发包的 init() 函数执行，而空包是显式声明“我存在，但你不该用我”。前者是副作用驱动，后者是意图驱动。
立即学习“go语言免费学习笔记（深入）”；
典型使用场景：
– 微服务项目中，每个子模块（如 auth、payment）都对应一个包路径，即使初期没实现逻辑，也要预留包结构，避免后续 import 路径断裂；
– CI 流水线需要提前注册插件入口，但插件本身由其他仓库提供，主仓库只保留包路径和接口定义。
-
_ import会导致包的init()运行，可能触发 DB 连接、配置加载等副作用；空包无init()，零开销 - 空包支持
go doc myproj/auth查文档；_ import的包若没doc.go，go doc找不到内容 - IDE（如 VS Code + gopls）对空包路径有完整补全和跳转支持；
_ import的包名在编辑器里常标灰、不可跳转
空包与 go:embed、go:generate 的兼容性
空包可以安全配合 go:embed 和 go:generate，但要注意顺序和作用域。它们不依赖包是否导出符号，只依赖文件是否属于该包。
比如在 assets/ 空包中放 doc.go 和 templates/ 目录，是可以用 //go:embed templates/* 加载模板的——只要 doc.go 在同一目录下，且 package assets 一致。
-
go:generate指令必须写在包内某个.go文件顶部，空包只要有文件就能用；但生成的代码如果要导出，就得另建非空包来接收 -
go:embed不要求包导出变量，所以var content = embed.FS{}可以放在空包里，但外部无法访问content——除非你再加一个导出变量，那就不是“空”了 - 如果嵌入大文件，空包仍会增加最终二进制体积；这不是 bug，是设计使然：embed 是编译期行为，和包是否“空”无关
容易被忽略的 import 路径一致性问题
空包最常踩的坑，不是语法，而是路径管理。Go 不允许两个不同目录声明同一个包名，也不允许同一目录下多个包名。这意味着：一旦你建了 internal/auth/doc.go（package auth），就不能再在 cmd/auth/ 下建另一个 package auth —— 否则 go build 报 found packages auth (doc.go) and auth (main.go)。
- 所有同名包必须严格对应唯一 import 路径；空包也不例外
- 重构时删掉空包目录，要全局 grep
"import.*auth"，确认没有残留引用，否则编译失败 - CI 中运行
go list ./...可提前发现非法包名重复，比等到go build报错更早
空包本身很简单，难的是在整个项目生命周期里保持 import 路径、包名、目录结构三者始终一致。人容易记混，工具不会——所以别省那几行 go list 检查。
