Go 入门: Air 配置热重载

前言

本章节适合 Golang 初学者，通过简单的项目实践来加深对 Golang 的基本语法和 Web 开发的理解。
参考文档：Air GO 官方文档

Air 简介

Air 是为 Go 应用开发设计的另外一个热重载的命令行工具。只需在你的项目根目录下输入 air，然后把它放在一边，专注于你的代码即可。

Air 出现的根本原因：
使用 Go 和 gin 框架开发网站时，由于 gin 缺乏实时重载功能，开发者不得不频繁使用 go run main.go 命令运行项目，每次修改代码都需要重新启动项目，导致开发效率低下。

注意：该工具与生产环境的热部署无关。

Air 特性：

• 彩色的日志输出
• 自定义构建或必要的命令
• 支持外部子目录
• 在 Air 启动之后，允许监听新创建的路径
• 更棒的构建过程

安装

1. 使用 go install (推荐)

需要 go 1.22 或更高版本:

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

此方法最为便捷，但需要 go 环境变量 GOPATH 已设置。

每日小技巧： go get vs go install

2. 使用 install.sh

# binary 文件安装在 $(go env GOPATH)/bin/air
curl -sSfL https://raw.githubusercontent.com/air-verse/air/master/install.sh | sh -s -- -b $(go env GOPATH)/bin

# 或者将其安装在 ./bin/ 路径下
curl -sSfL https://raw.githubusercontent.com/air-verse/air/master/install.sh | sh -s

air -v

3. 使用 goblin.run

# binary 将会安装到 /usr/local/bin/air
curl -sSfL https://goblin.run/github.com/cosmtrek/air | sh

# 自定义路径安装
curl -sSfL https://goblin.run/github.com/cosmtrek/air | PREFIX=/tmp sh

4. Docker/Podman

请拉取 Docker 镜像 cosmtrek/air

docker run -it --rm \
    -w "<PROJECT>" \
    -e "air_wd=<PROJECT>" \
    -v $(pwd):<PROJECT> \
    -p <PORT>:<APP SERVER PORT> \
    cosmtrek/air
    -c <CONF>

4.1 Docker/Podman .${SHELL}rc

如果你想像正常应用程序一样连续使用 air，你可以在你的 ${SHELL}rc（Bash, Zsh 等）中创建一个函数

air() {
  podman/docker run -it --rm \
    -w "$PWD" -v "$PWD":"$PWD" \
    -p "$AIR_PORT":"$AIR_PORT" \
    docker.io/cosmtrek/air "$@"
}

<PROJECT> 是容器中的项目路径，例如：/go/example
如果你想进入容器，请添加 --entrypoint=bash。

具体实例请参照官方文档：Air GO 官方文档

使用方法

为了输入方便，您可以添加 alias air='~/.air' 到您的 .bashrc 或 .zshrc 文件中.

1. 进入你的项目文件夹

cd /path/to/your_project

注意：请替换 /path/to/your_project 为你的项目文件夹路径。

2. 最简单的方法是执行

air -c .air.toml

这行代码的意思是告诉 air 在当前路径下查找并使用名为 .air.toml 的配置文件来启动你的项目。
如果你没有找到 .air.toml 文件，air 将会使用默认配置启动你的项目。

3. 您也可以运行如下命令，将具有默认设置的 .air.toml 配置文件初始化到当前目录。

air init

如果以上都正常，您只需执行 air 命令，就能使用 .air.toml 文件中的配置热重载你的项目了。

air

注意：请确保你的项目文件夹中有 main.go 文件，否则 air 命令无法启动。

如欲修改配置信息，请参考如下文档。

.air.toml 配置文件详解

配置项	说明
root	. 设置 air 的根目录，也就是运行 air 命令的目录。
testdata_dir	testdata 指定测试数据目录。
tmp_dir	tmp 指定编译后生成文件的临时目录。

[build] 部分

配置项	说明
args_bin	[] 传递给二进制文件的额外参数，通常留空。
bin	tmp\\main.exe 指定生成的二进制文件的路径。
cmd	go build -o ./tmp/main.exe . 构建命令。.表示在当前路径寻找 main.go 文件
delay	1000 文件变更后的构建延迟时间，单位是毫秒。
exclude_dir	["assets", "tmp", "vendor", "testdata"] 排除的目录。
exclude_file	[] 需要排除的文件。
exclude_regex	["_test.go"] 排除的文件名模式。
exclude_unchanged	false 是否不重新构建未改变的文件。
follow_symlink	false 是否跟随符号链接。
full_bin	"" 完整的二进制文件路径，通常留空。
include_dir	[] 需要包含的目录。
include_ext	["go", "tpl", "tmpl", "html"] 需要包含的文件扩展名。
include_file	[] 需要包含的文件。
kill_delay	0s 停止进程前的延迟时间。
log	build-errors.log 构建错误日志文件路径。
poll	false 是否使用轮询检测文件变化。
poll_interval	0 轮询间隔时间，单位是毫秒。
post_cmd	[] 构建后执行的命令。
pre_cmd	[] 构建前执行的命令。
rerun	false 是否在文件变更后重新运行应用。
rerun_delay	500 文件变更后重新运行应用的延迟时间，单位是毫秒。
send_interrupt	false 是否发送中断信号。
stop_on_error	false 遇到错误时是否停止应用。

[color] 部分

配置项	说明
app	"" 应用输出颜色。
build	yellow 构建输出颜色。
main	magenta 主应用输出颜色。
runner	green 运行器输出颜色。
watcher	cyan 监视器输出颜色。

[log] 部分

配置项	说明
main_only	false 是否只记录主日志。
time	false 是否在日志中包含时间戳。

[misc] 部分

配置项	说明
clean_on_exit	false 是否在退出时清理生成的临时文件。

[proxy] 部分

配置项	说明
app_port	0 应用端口号，0 表示未启用。
enabled	false 是否启用代理。
proxy_port	0 代理端口号。

[screen] 部分

配置项	说明
clear_on_rebuild	false 是否在重建时清除屏幕。
keep_scroll	true 是否在重建时保留滚动位置。

常见问题

1. 问题：遇到 "command not found: air" 或 "No such file or directory" 该怎么办？

export GOPATH=$HOME/xxxxx
export PATH=$PATH:$GOROOT/bin:$GOPATH/bin
export PATH=$PATH:$(go env GOPATH)/bin <---- 请确认这行在您的配置信息中！！！

GOPATH 和 GOROOT 的区别及配置

属性	GOPATH	GOROOT
定义	GOPATH 是 Go 代码的工作目录，包含你的源代码、包和可执行文件。	GOROOT 是 Go 安装目录，包含 Go 语言的标准库和工具。
用途	用于指定 Go 项目的工作空间，包含项目的源代码和依赖包。	用于指定 Go 语言的安装位置，包含 Go 的核心组件。
默认值	默认值是 $HOME/go（在 Unix 系统中）或 %USERPROFILE%\go（在 Windows 中）。	默认值通常是 Go 的安装目录，取决于安装方式。
配置方法	Unix/Linux/MacOS: export GOPATH=$HOME/go Windows: set GOPATH=%USERPROFILE%\go	Unix/Linux/MacOS: export GOROOT=/usr/local/go Windows: set GOROOT=C:\Go

配置示例

操作系统	GOPATH 配置	GOROOT 配置
Unix/Linux/MacOS	bash<br>export GOPATH=$HOME/go<br>	bash<br>export GOROOT=/usr/local/go<br>
Windows	cmd<br>set GOPATH=%USERPROFILE%\go<br>	cmd<br>set GOROOT=C:\Go<br>

配置完成后，建议将这些设置添加到你的 shell 配置文件（如 .bashrc 或 .zshrc）中，以便每次启动终端时自动加载这些环境变量。

2. 问题：如何只进行热编译而不运行？

可参考原问题

[build]
  cmd = "/usr/bin/true"

3. 问题：如何在静态文件更改时自动重新加载浏览器?

请参考 可参考原问题.

• 确保你的静态文件在 include_dir、include_ext 或 include_file 中。
• 确保你的 HTML 文件内至少有一个 </body> 标签。
• 通过配置以下内容开启代理：

[proxy]
  enabled = true
  proxy_port = <air proxy port>
  app_port = <your server port>

你需要将 <air proxy port> 和 <your server port> 替换为实际使用的端口号。这个端口号是 air 工具用来与代理服务器通信的端口。

假设你的代理端口是 8080，你的应用程序端口是 3000，那么你的配置可能看起来像这样：

[proxy]
  enabled = true
  proxy_port = 8080
  app_port = 3000