Air是监听源码变化、自动go build并重启进程的开发期工具，不参与项目结构设计；安装需用go install github.com/air-verse/air@latest，PATH须包含$(go env GOPATH)/bin，配置需手动调整include_ext、exclude_dirs和bin路径。
直接上结论：Air 不是“构建项目”，而是监听源码变化、自动 go build + 重启进程的开发期辅助工具；它不参与项目结构设计，也不改变 Go 编译模型，只解决“改完代码要手动编译再启动”这个重复劳动问题。
air 命令找不到？PATH 和安装地址是最大拦路虎
绝大多数人卡在第一步：终端输入 air 报错 command not found 或 air 不是内部或外部命令。这不是 Air 本身的问题，而是环境没对齐。
- 安装必须用新仓库地址：
go install github.com/air-verse/air@latest（旧地址cosmtrek/air已失效，会报 module path 冲突） - 二进制默认落在
$(go env GOPATH)/bin（Windows 是%USERPROFILE%\go\bin），这个路径必须加进系统PATH环境变量 - 加完 PATH 后，**必须重启终端或 IDE（如 GoLand）**，否则 shell 不会重新读取
- 验证方式不是看有没有提示，而是执行
air -v，输出类似v1.67.4, built with Go go1.26.3才算真正可用
.air.toml 配置里最常踩的三个坑
不配 .air.toml 也能跑，但一改 go.mod 或加个 .proto 就失效——因为默认配置根本不监听这些文件。
-
include_ext必须显式加"mod"和"sum"，否则改依赖后不会触发重建 -
exclude_dirs一定要包含"vendor"和"tmp"，否则 vendor 更新或临时文件写入都会反复重启 -
bin路径必须和cmd输出完全一致，比如cmd = "go build -o ./tmp/main ."对应bin = "./tmp/main"；路径错一个点或斜杠，就会报exec: "./tmp/main": file does not exist
微服务或多 cmd 目录下 air 启动失败的真实原因
你在 cmd/user-svc 里跑 air 却提示 main package not found？不是代码问题，是工作目录和配置没对齐。
立即学习“go语言免费学习笔记（深入）”；
- Air 默认从当前目录找
go.mod，再按 Go Modules 规则解析main包——所以必须在项目根目录（含go.mod）运行air，而不是在cmd/xxx子目录 - 如果入口在
cmd/user-svc/main.go，.air.toml中的bin应设为"./cmd/user-svc/user-svc"，cmd设为"go build -o ./cmd/user-svc/user-svc ./cmd/user-svc" - 多个服务共存时，别共用一个
.air.toml；每个服务应有独立配置，并用air -c cmd/user-svc/.air.toml指定路径启动 - 端口冲突不是 Air 的锅，而是环境变量没隔离；在各自配置里用
env = ["USER_SVC_PORT=8001"]注入，别全局 export PORT
改了代码却没重启？先看 build-errors.log 和终端末尾红字
Air 不会隐藏编译错误，它只是把 go build 的失败结果原样抛出来。你看到“没反应”，大概率是构建失败后 Air 自动退出了，而你没注意到那一屏红色报错。
- 检查
build-errors.log（如果你在配置里写了log = "build-errors.log"），或者直接翻终端最后 10 行 - 高频错误是
undefined: xxx（拼写错）、import cycle（循环引用）、或cannot find package（go mod tidy 没做） - 还有种静默失败：Linux/macOS 上
./tmp/main没执行权限，报permission denied；可在cmd里追加&& chmod +x ./tmp/main - 别迷信
air init生成的配置——它只是模板，root、bin、include_ext这三项必须按你项目真实结构手调
真正难的从来不是装上 Air，而是当它每次重启都慢半拍、日志里出现 failed to kill process、或者 DB 连接池刚关一半新进程就抢着连——这些不会打断构建，但会让热重载“看起来生效了，实际接口全挂”。这时候得盯住进程树和连接状态，而不是反复重装 Air。
