Air 是 Go 生态中唯一可行的 Iris 热重载方式,通过监听文件变化触发完整进程重启,而非 Iris 的 Party+Reset() 运行时路由重注册;后者不重建中间件、DB 连接或全局配置,仅适用于极少数运维场景。

Air 不能直接“集成”进 Iris 框架,Iris 本身不提供热重载能力;你真正要做的,是用 Air 监听 Iris 项目文件变化、触发进程重启 —— 这是 Go 生态里唯一可行的热重载方式。
为什么 Iris 的 Party + Reset() 不等于 Air 热重载
Iris 的 Party 分组和 Reset() 是运行时路由动态重注册机制,它不重启进程、不重新加载中间件、不重建数据库连接、不更新全局配置变量。它只适用于极少数场景:比如权限路由表从 DB 加载后想刷新一次,且你已手动管理好所有依赖状态。而 Air 触发的是完整进程重启,所有初始化逻辑(app := iris.New()、中间件注册、DB 连接池创建、配置解析)全部重跑。两者解决的问题完全不同:Reset() 是运维期动态路由管理,Air 是开发期快速反馈循环。
- 改了
app.Use(iris.Compression)?Reset()完全无效,必须重启 - 改了
viper.SetConfigFile("config.yaml")后的内容?Reset()不读新文件,Air 重启也不自动生效,得自己加viper.WatchConfig()回调 - 在
main.go里加了个新app.Get("/debug", ...)?只有 Air 重启才让这个路由出现
air 启动失败常见错误及修复
Air 启动报错 90% 和 Iris 无关,而是环境或配置问题。终端最后一行红字才是关键线索:
-
failed to build: undefined: xxx→ 先执行go build,确认是 Iris 代码编译错误(比如漏写ctx.Next()或中间件签名不对),不是 Air 配置问题 -
cannot find module providing package→ 检查当前目录是否有go.mod,Air 默认从含go.mod的根目录启动,别在cmd/api/下直接跑air -
fork/exec ./tmp/main: permission denied(macOS/Linux)→ 在.air.toml的[build]节里补上cmd = "go build -o ./tmp/main . && chmod +x ./tmp/main",并确保bin = "./tmp/main"和 cmd 输出路径一致 -
watch: no such file or directory→exclude_dirs列表里漏了vendor或.git,导致监听失败;正确写法:exclude_dirs = ["vendor", "tmp", ".git", ".air"]
.air.toml 关键配置项(适配 Iris 项目)
Iris 项目通常含 main.go、go.mod、config/、handlers/ 等目录,Air 需明确知道监听什么、忽略什么、怎么构建:
-
include_exts = ["go", "mod", "sum", "yaml", "yml", "json", "html", "tmpl"]→ 必须包含mod和sum,否则改go.mod不触发重建;如果 Iris 用了模板,加上html/tmpl -
exclude_dirs = ["vendor", "tmp", ".git", ".air", "migrations"]→ 排除migrations可避免数据库迁移文件变更误触发重启 -
build.cmd = "go build -o ./tmp/main ."→ Iris 项目一般不需额外-tags,保持简洁;若用了 CGO,加CGO_ENABLED=1前缀 -
build.bin = "./tmp/main"→ 必须和cmd输出路径完全一致,少个.或多层../都会失败 - 不要在
[watch]和[build]两节里写不同include_exts,否则非.go文件修改不会触发构建
改配置文件(如 config.yaml)后如何真正热生效
Air 重启进程只是第一步。Iris 应用里的配置(比如端口、DB 地址、JWT 密钥)通常在 main() 开头就解析完毕,Air 重启后自然读新值 —— 但这是“冷热更”,不是“热加载”。如果你希望不重启也能更新配置:
- 用
viper.WatchConfig()注册监听,但它**只监听,不自动重读**;必须在回调里显式调viper.ReadInConfig()和viper.Unmarshal(&conf) - 用
sync.RWMutex或atomic.Value包裹配置结构体指针,业务代码统一通过conf.Load().(*Config)获取,禁止缓存旧指针 - 注意并发安全:DB 连接池大小变更后,要调
db.SetMaxOpenConns();HTTP 超时参数无法热更,只能 graceful restart - 别指望 Air 替你做这事 —— 它只管进程生命周期,配置热加载是你自己的责任
最常被忽略的一点:Iris 的中间件注册顺序、全局 app.RegisterView、静态文件路径绑定,全在 main() 函数里一次性完成。Air 重启是唯一能让这些变更生效的方式;任何试图绕过重启、只靠 Reset() 或反射重载的方案,都会在中间件状态、Context 生命周期、模板缓存等环节出问题。











