🧠 Air 热重载 Go 应用程序 —— 笔记总结

一、什么是 Air？

Air 是一个为 Go 开发者设计的热重载工具。
它可以在你修改代码后，自动重新编译并重启服务，提升开发效率。
支持自定义配置，适合各种 Go Web 框架（如 Gin、Echo、Fiber 等）。

GitHub 地址：https://github.com/air-verse/air

二、安装 Air

go install github.com/air-verse/air@latest

确保 $GOPATH/bin 已加入环境变量 PATH：

export PATH=$PATH:$(go env GOPATH)/bin

验证是否安装成功：

air -v

三、初始化配置文件

在项目根目录下运行：

air init

会生成 .air.toml 配置文件。

四、启动热重载

air

之后每次保存 Go 文件或其他指定类型的文件时，Air 就会自动构建并重启服务。

五、常用配置项详解（`.air.toml`）

✅ [build] 构建配置（重点）

配置项	示例值 / 说明
`cmd`	`"go build -o ./tmp/app main.go"` 编译命令
`bin`	`"./tmp/app"` 编译后的可执行文件路径
`delay`	`1000` 修改代码后延迟多少毫秒再构建
`exclude_dir`	`["assets", "tmp", "vendor"]` 不监听这些目录
`exclude_regex`	`["_test.go"]` 排除匹配正则表达式的文件
`include_ext`	`["go", "tpl", "tmpl", "html"]` 监听哪些扩展名
`log`	`"build-errors.log"` 构建错误日志输出文件

🎨 [color] 控制台颜色（非必需）

配置项	示例值	含义
`build`	`"yellow"`	构建阶段日志颜色
`main`	`"magenta"`	主程序日志颜色
`runner`	`"green"`	运行器日志颜色
`watcher`	`"cyan"`	文件监听器日志颜色

📝 [log] 日志设置

配置项	示例值	含义
`main_only`	`false`	是否只显示主程序日志
`silent`	`false`	是否关闭所有日志
`time`	`false`	是否显示时间戳

⚙️ 其他配置（一般默认即可）

[misc]: 清理临时文件等
[proxy]: 反向代理功能（高级用途）
[screen]: 终端显示控制

六、推荐最小配置（适用于大多数 Web 项目）

[build]
  cmd = "go build -o ./tmp/app main.go"
  bin = "./tmp/app"
  delay = 1000
  exclude_dir = ["tmp", "vendor", "testdata"]
  exclude_regex = ["_test.go"]
  include_ext = ["go", "mod", "html", "tpl", "tmpl"]

七、常见问题与解决

问题	原因	解决方案
`command not found: air`	未正确安装或 PATH 未配置	重新安装并检查 `$GOPATH/bin` 是否加入 PATH
`module declares its path as: github.com/air-verse/air`	使用了旧地址安装	改用 `github.com/air-verse/air` 安装
修改代码不触发重启	配置监听范围不对	检查 `include_ext` 和 `exclude_dir` 设置

八、使用场景示例

✅ Gin Web 项目结构

my-gin-app/
├── main.go
├── go.mod
├── .air.toml
└── handlers/
    └── user.go

修改任意 .go 或 .html 文件后，Air 自动构建并重启服务。

九、优点总结

✅ 提高开发效率，无需手动重启服务
✅ 支持多种构建和监听策略
✅ 彩色日志，调试更清晰
✅ 支持自定义脚本（pre_cmd, post_cmd）

十、附录：完整 `.air.toml` 示例

root = "."
testdata_dir = "testdata"
tmp_dir = "tmp"

[build]
  bin = "./tmp/app"
  cmd = "go build -o ./tmp/app main.go"
  delay = 1000
  exclude_dir = ["assets", "tmp", "vendor", "testdata"]
  exclude_regex = ["_test.go"]
  include_ext = ["go", "mod", "html", "tpl", "tmpl"]

[color]
  build = "yellow"
  main = "magenta"
  runner = "green"
  watcher = "cyan"

[log]
  silent = false
  time = false

Air 热重载 Go 应用程序 —— 笔记总结