Air与Fresh热重载配置全解析

Go官方不支持热重载，直接反复使用`go run`会导致端口占用、进程残留和手动重启低效等痛点，必须借助Air或Fresh等外部工具实现自动构建、优雅重启与信号转发；其中Air依赖精细的`.air.toml`配置（如显式指定root、tmp_dir及include_ext），对模块结构敏感但更精准，而Fresh配置更轻量但需手动指定BuildCmd/RunCmd且不解析go.mod，两者均不监听go.sum变更——升级依赖后务必手动重启，本文详解二者核心差异、典型报错（如fresh找不到runner、air子目录不重载）及生产级避坑配置，助你告别Ctrl+C+go run的无效循环。

Go 热重载为什么不能直接 go run 反复执行？

因为 go run 每次都编译新进程，旧进程没被清理，端口会报 address already in use；同时无法监听文件变化，纯手动 Ctrl+C + 重新敲命令，效率低且易漏。

• 真实场景：改一行 main.go 就得切终端、杀进程、再 go run，调试 HTTP 服务时尤其烦躁
• 根本原因：Go 官方不内置热重载，得靠外部工具接管构建 + 启动 + 信号转发生命周期
• 关键约束：工具必须能捕获 SIGHUP 或类似信号，优雅终止旧进程后再拉起新实例，否则 socket 资源泄漏

Air 配置文件 .air.toml 必须写的三处

air 强依赖配置文件，空跑或只改命令行参数大概率失败——它默认不扫描子目录、不重载 go.mod、甚至忽略 vendor/ 变更。

• root = "."：显式指定项目根目录，否则可能从 $PWD 开始扫描，遇到嵌套模块就错位
• tmp_dir = "tmp"：必须设为不存在的目录名（air 会自动创建），否则并发多次保存时生成的临时二进制可能冲突
• include_ext = ["go", "tpl", "tmpl", "html"]：加 "env" 如果用 godotenv，加 "sql" 如果模板里拼 SQL，漏掉就等于“改了但没热重载”

示例最小可用配置：

[build]
  cmd = "go build -o ./tmp/main ."
  bin = "./tmp/main"
  include_ext = ["go", "env"]
  exclude_dir = ["assets", "node_modules", "tmp"]

[watch]
  exclude_dir = ["tmp", "vendor"]

Fresh 启动报 fork/exec ./runner: no such file or directory

这是 fresh 的经典陷阱：它默认找当前目录下的 runner 二进制，但 Go 项目几乎不用这个名字，也不自动生成。

• 错误做法：手动 go build -o runner . —— 下次改代码后 fresh 仍运行旧二进制，因为没触发重建
• 正确解法：在 fresh.conf 里写死 BuildCmd，例如 BuildCmd = "go build -o tmp/app ."，再配 RunCmd = "tmp/app"
• 兼容性注意：fresh 不支持 GOOS=js 或交叉编译，Windows 上路径分隔符要用 \\，否则 RunCmd 找不到 exe

Air 和 Fresh 在 module 多级嵌套时的行为差异

当项目含 cmd/api、internal/pkg、pkg/lib 多个 go.mod 时，两者处理方式截然不同。

• air 默认只认根目录的 go.mod，子模块变更不会触发重载——必须在 .air.toml 的 watch.include_dir 里手动加 ["cmd", "internal", "pkg"]
• fresh 根本不解析 go.mod，只按文件路径匹配，所以只要 include_ext 覆盖了所有 .go 文件，多模块也能 reload，但可能误触无关构建
• 性能影响：air 的模块感知更准，但配置复杂；fresh 简单粗暴，小项目快，大项目 watch 文件过多会卡顿

真正容易被忽略的是：两者都不监控 go.sum 变更。升级依赖后，必须手动重启工具，否则新包代码不会生效。

今天关于《Air与Fresh热重载配置全解析》的内容就介绍到这里了，是不是学起来一目了然！想要了解更多关于的内容请关注golang学习网公众号！