air启动失败主因是配置错误而非工具故障：需确保root指向含go.mod的根目录、build.bin与build.cmd路径严格一致、include_ext在[watch]和[build]两节均正确配置。
air 启动失败：常见报错和对应解法
直接运行 air 却报错，大概率不是工具坏了，而是环境或配置没对上。最常遇到的两类错误，背后原因完全不同。
-
failed to build, error: exit status 2：这不是 air 的问题，是你的 Go 代码根本编译不过。立刻看终端最后一屏的红色输出——90% 是undefined: xxx或import cycle not allowed。别急着改.air.toml，先go build手动试一遍。 -
fork/exec ./tmp/main: permission denied：Linux/macOS 上很典型。要么./tmp目录没写权限，要么生成的二进制被挂载策略 strip 掉了执行位。实操建议是把build.cmd改成：go build -o ./tmp/main . && chmod +x ./tmp/main，同时确保build.bin和它完全一致。 -
air: failed to kill process: no such process：其实是上一次 panic 后进程僵死、但 pid 文件残留。手动清掉就行：pkill -f 'tmp/main'（macOS/Linux）或taskkill /F /IM main.exe（Windows）。
修改模板或 YAML 配置后不重启？默认不监听非 .go 文件
air 定位是 Go 代码热重载，不是全栈 Live Reload。它默认只 watch .go 文件，config.yaml、templates/*.html 这类文件压根不在监控列表里——这不是 bug，是设计如此。
- 必须在
.air.toml的[watch]和[build]两节都显式加后缀，例如：include_ext = ["go", "yaml", "yml", "html", "tmpl"]；漏掉任意一节，都不生效。 - 加太多后缀有代价：Linux 下 inotify 句柄有限（默认单进程最多 8192 个），项目大了容易触发
inotify limit reached。宁可少加，别乱堆。 - 如果只是改文案或静态资源，更推荐让程序自己监听 reload（比如用
fsnotify加载模板），而不是靠 air 杀进程重启——状态更干净，也避免 HTTP 连接中断。
配置文件怎么写才真正起作用
很多人生成了 .air.toml 却发现改了不触发，问题往往出在三个字段没对齐：监控范围、构建命令、输出路径。
-
root = "."必须是项目根目录（即含go.mod的那层），不是main.go所在目录；否则 air 根本找不到你要监听的包。 -
build.cmd和build.bin必须严格匹配。比如写了cmd = "go build -o ./tmp/main ."，那bin就得是"./tmp/main"，不能是"tmp/main"或"./main"，否则 air 启动时会报exec: "./tmp/main": file does not exist。 -
delay = 1000别乱调小。设成 200ms 看似快，但编辑器保存瞬间文件可能还没刷盘，导致构建失败。1000ms 是平衡点，够稳也够快。
Windows 下 permission denied 怎么办
本质是 Windows 权限模型和 Go 构建产物不兼容：air 试图直接执行 main.exe，但杀毒软件或组策略会拦截未签名二进制。
- 最稳做法：把
build.bin和build.cmd都明确带上.exe后缀，例如：bin = "./tmp/main.exe"，cmd = "go build -o ./tmp/main.exe ."。 - 临时验证是否是 Defender 拦截：关掉实时防护，或把
tmp/目录加进排除列表。如果好了，就说明是安全策略问题，不是 air 配置错误。 - 别信“管理员运行 CMD 就行”——air 启动的是子进程，权限继承自父 shell，不是靠提权解决的。
真正卡住人的从来不是 air 装不上，而是 root、bin、include_ext 这三个字段有一处没对齐，或者人在子目录下却以为自己在项目根目录。多看一眼 go env GOPATH 和当前路径，比反复重装有效得多。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
