Air：Go热重载工具

Air：Go热重载工具

什么是 Air？

Air 是一个 Go 项目的热重载工具，作用是在你修改代码文件后自动重新编译并重启程序，从而大幅提升开发效率，避免手动重启程序的繁琐操作。

适用于：Go Web 项目、API 服务、后台脚本开发等需要频繁修改测试的场景。

GitHub 地址：https://github.com/cosmtrek/air

---

安装方式

✅ 方式一：使用 go install

go install github.com/cosmtrek/air@latest

然后确保 $GOPATH/bin 或 $HOME/go/bin 已加入 PATH。

✅ 方式二：使用 Brew（macOS）

brew install cosmtrek/tap/air

✅ 验证安装

air -v

---

项目结构（示例）

myapp/
├── .air.toml           # Air 配置文件（可选）
├── main.go
├── handler/
│   └── home.go
└── go.mod

---

⚙️ 配置文件 .air.toml（支持自动生成）

生成配置文件

air init

生成 .air.toml 配置文件，默认内容类似如下：

# 配置文件格式
root = "."                     # 项目根目录
tmp_dir = "tmp"                # 临时构建文件目录

[build]
  cmd = "go build -o ./tmp/main ."   # 构建命令
  bin = "tmp/main"                   # 可执行文件路径
  include_ext = ["go", "tpl", "tmpl", "html"]  # 热重载监听的文件后缀
  exclude_dir = ["assets", "tmp", "vendor"]    # 排除的目录
  exclude_file = []                         # 排除的文件
  follow_symlink = true
  delay = 1000                              # debounce 毫秒数，避免多次触发

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

---

▶️ 使用方式

启动热重载

air

• 它会监听项目中 .go 文件变化；
• 检测到变动时，会运行 go build；
• 构建成功后，自动重新运行程序。

---

使用原理（深入）

Air 的核心机制如下：

1. 监听文件变化：
   使用 fsnotify 检测指定目录下文件（如 .go, .html）的更改。

2. 触发重新构建：
   改动发生后调用 go build 编译成临时可执行文件（默认存放在 tmp 目录）。

3. 热重启进程：
   构建成功后，终止旧进程，启动新进程。

4. 日志输出美化：
   使用颜色标签区分不同日志，如构建器、监视器、运行器等，增强可读性。

---

常见问题与排查

❓ 修改代码后不生效？

• 检查文件是否包含在 include_ext 中；
• 检查 .air.toml 中的 exclude_dir 是否误排除了某个目录；
• 检查是否保存了文件（仅保存后会触发）。

❓ 为什么重启慢？

• 可能构建时间长，可优化代码结构；
• 使用更快的磁盘（例如 SSD）；
• 简化 go build 命令（避免构建所有包）。

❓ 有多个 main 函数？

• 确保 cmd 指令中指明了具体包目录，例如：

  cmd = "go build -o ./tmp/main ./cmd/myservice"
  

---

‍ 实战建议

提高构建速度

• 拆分多个服务子目录，只构建当前服务目录；
• 配合 go mod tidy 保持依赖整洁；
• 可使用 taskfile.yml 搭配 air 自动做更多事情（如数据库重启、迁移等）。

️ 结合 .env 管理环境变量

• 在 .air.toml 配置中添加：

  [env]
    APP_ENV = "dev"
    DB_URL = "postgres://localhost"
  

在 Docker 中使用（仅开发场景）

Dockerfile 示例：

FROM golang:1.20

WORKDIR /app
COPY . .
RUN go install github.com/cosmtrek/air@latest

CMD ["air"]

---

总结

特性	说明
热重载	自动监听文件变化，重新构建运行
自定义构建	支持 .air.toml 完全定制构建流程
扩展性强	可搭配 Makefile, Task, Docker 等使用
跨平台支持	Windows / macOS / Linux 都能用