一、工具概述

Air（仓库已迁移至 air-verse/air）是 Go 生态最主流、维护活跃的本地开发热重载工具，核心能力：监听项目文件变更 → 自动编译代码 → 杀死旧进程、启动新版本程序，无需手动执行 go build/go run，大幅提升接口/服务迭代效率。

重要区分：Air 仅用于本地开发环境，属于「进程重启式热重载」，不支持生产零停机平滑升级、不支持运行时无重启替换函数，生产环境热更新需使用 endless/grace 等信号平滑重启库。

二、安装教程

1. 报错根源说明

早期教程均使用旧地址 github.com/cosmtrek/air，当前仓库已整体迁移至 github.com/air-verse/air，使用旧地址执行 go install 会报 module path 冲突，无法完成安装。

2. 标准安装命令（唯一可用）

# Go1.16+ 推荐，全局安装最新版
go install github.com/air-verse/air@latest

3. 安装校验

# 输出版本号即安装成功
air -v

4. 常见问题：command not found

Go 全局工具默认安装至 $GOPATH/bin，需将该目录加入系统环境变量：

# Mac / Linux(zsh)
echo 'export PATH=$PATH:$(go env GOPATH)/bin' >> ~/.zshrc
source ~/.zshrc

# bash 用户
echo 'export PATH=$PATH:$(go env GOPATH)/bin' >> ~/.bashrc
source ~/.bashrc

5. 备选一键脚本安装（网络差场景）

# Mac/Linux
curl -fsSL https://raw.githubusercontent.com/air-verse/air/master/install.sh | sh -s -- -b $(go env GOPATH)/bin

三、基础使用（开箱即用，无需配置文件）

1. 启动热重载

进入项目根目录（存在 main.go、go.mod），直接执行：

air

默认行为：

• 监听 .go/.tpl/.tmpl/.html 文件修改
• 自动执行 go build 编译至 tmp/main
• 变更后自动杀死旧服务，重启新版本

2. 退出 Air 运行

1. 前台运行（最常用）：终端快捷键 Ctrl + C，自动清理 tmp 临时目录
2. 后台运行（nohup/&）

   # 查找进程PID
   ps aux | grep air
   # 终止进程
   kill -9 PID
   # 一键杀掉所有air进程
   pkill air
   

四、进阶配置：.air.toml 完整实践

1. 生成默认配置文件

air init

项目根目录生成 .air.toml，可自定义监听、编译、环境变量、日志规则。

2. 通用生产开发配置（Gin/Echo/标准HTTP直接复制）

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

[build]
  args_bin = []
  bin = "./tmp/main"
  # 标准编译命令
  cmd = "go build -o ./tmp/main ."
  # 防抖延迟，短时间多次修改仅编译一次
  delay = 1000
  # 排除无需监听的目录
  exclude_dir = ["assets", "tmp", "vendor", "testdata", "logs", "node_modules"]
  exclude_file = []
  exclude_regex = ["_test.go"]
  follow_symlink = false
  # 自定义运行环境变量
  full_bin = "APP_ENV=dev DB_DSN=postgres://127.0.0.1 ./tmp/main"
  include_dir = []
  # 需要监听的文件后缀
  include_ext = ["go", "tpl", "tmpl", "html", "yaml"]
  kill_delay = "500ms"
  log = "build-errors.log"
  send_interrupt = true
  stop_on_root = false

# 自定义控制台彩色输出
[color]
  app = "cyan"
  build = "yellow"
  main = "magenta"
  runner = "green"
  watcher = "blue"

[log]
  time = true

# 退出自动清理tmp编译缓存
[misc]
  clean_on_exit = true

# 重启清空终端屏幕
[screen]
  clear_on_rebuild = true
  scrollback = 100

# 单独配置环境变量（推荐分离）
[env]
  PORT = "8080"
  REDIS_ADDR = "127.0.0.1:6379"

3. 核心配置项说明

配置段	关键字	作用
[build].cmd	go build …	自定义编译命令，支持 make、CGO 编译
[build].exclude_dir	[“tmp”,“vendor”]	屏蔽目录变更触发重启，减少无效编译
[build].delay	1000	文件防抖毫秒，高频修改避免重复构建
[build].full_bin	环境变量+程序	启动时注入开发环境配置，无需改代码
[env]	自定义键值	统一管理开发环境变量
[misc].clean_on_exit	true	Ctrl+C退出自动删除tmp缓存

五、常用命令行参数（无需修改配置文件）

# 指定自定义配置文件启动
air -c .air.toml

# 仅打印构建日志，屏蔽业务服务输出
air --log.main=false

# 临时自定义编译命令
air --build.cmd "go build -tags dev -o tmp/main ."

# 禁用彩色日志
air --color=false

六、Air 核心优势（特点）

1. 跨平台全兼容
   Windows/macOS/Linux 完美支持，适配所有 Go 主流框架（Gin/Echo/GRPC/标准net/http）。
2. 配置高度灵活
   支持自定义监听目录、过滤文件、注入环境变量、自定义构建脚本，适配多模块、带静态模板的复杂后端项目。
3. 友好可视化日志
   彩色区分监听、编译、运行日志，编译错误单独输出，快速定位代码语法问题。
4. 稳定可靠，社区活跃
   替代多年未维护的 fresh，持续迭代，支持 Go Module 规范，文件监听无丢失、无卡死问题。
5. 轻量化低资源占用
   仅做文件监听与进程管理，内存、CPU 消耗极低，可同时运行多个后端服务。
6. 配套开发友好特性
   退出自动清理编译缓存、支持中断信号优雅关闭进程、修改模板/yml配置文件也可触发重启。

七、Air 短板与使用限制（重点避坑）

1. 本质是「重启进程」，非真正运行时热更新

每次修改代码会杀死原有进程、新建二进制：

• 内存内临时数据、缓存、连接池会全部丢失；
• 长连接（WebSocket/GRPC流）会直接断开；
• 无法实现 Java 式「不重启进程替换函数逻辑」。

2. 仅适用于本地开发，严禁上生产

Air 无平滑重启、连接保活、进程托管能力，生产环境零停机升级需使用 endless/grace 信号方案。

3. 大型项目编译耗时较长

单体百万行代码项目，每次变更全量编译存在等待耗时，无增量编译优化；微服务多模块项目建议拆分监听目录。

4. 存在文件监听上限限制

Linux 系统 inotify 文件句柄有限，超大型项目可能出现监听失效，需手动调大系统文件监控数量。

5. 不支持测试场景自动化

默认排除 _test.go 文件，无法自动执行单元测试，测试仍需手动 go test。

6. CGO 编译场景兼容性差

带 CGO 依赖项目编译速度大幅下降，部分交叉编译场景会出现构建缓存异常。

八、最佳实践规范

1. .gitignore 配置

   # Air 临时编译目录
   tmp/
   # 构建错误日志
   tmp/build-errors.log
   

2. 项目统一配置模板
   团队项目根目录统一提交 .air.toml，所有人共享一致开发环境，避免本地环境差异。
3. 区分开发/生产工具
   • 本地迭代：air
   • 线上服务平滑重启：endless / grace
   • 运行时动态插件：官方 plugin / yaegi
4. 多服务并行开发
   每个后端目录独立运行 air，通过端口区分服务，互不干扰。

九、常见故障排查

1. 修改代码无自动重启
   检查 include_ext 是否包含目标文件后缀、exclude_dir 未屏蔽业务代码目录。
2. 端口占用、进程未正常关闭
   增加 send_interrupt = true，延长 kill_delay 优雅关闭等待时间。
3. 编译缓存异常报错
   手动删除 tmp 文件夹，重新执行 air。
4. macOS 监听延迟高
   调小 delay 至 300~500ms，减少防抖等待。