:cloud: Air - Go 应用程序的实时重载工具

English | 简体中文 | 繁體中文

动机

当我开始使用 Go 开发网站并使用 gin 框架时，遗憾的是 gin 缺少实时重载功能。所以我四处寻找并尝试了 fresh，但它似乎不够灵活，所以我打算重写一个更好的版本。最终，Air 诞生了。 此外，非常感谢 pilu，没有 fresh，就没有 air :)

Air 是另一个用于开发 Go 应用程序的实时重载命令行工具。在项目根目录运行 air，然后专注于你的代码即可。

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

特性

• 彩色日志输出
• 自定义构建或任何命令
• 支持排除子目录
• 允许在 Air 启动后监视新目录
• 更好的构建流程

通过参数覆盖指定配置

支持将 air 配置字段作为参数：

如果你想配置构建命令和运行命令，可以使用以下命令而无需配置文件：

air --build.cmd "go build -o bin/api cmd/run.go" --build.bin "./bin/api"

对于接受列表作为输入的参数，使用逗号分隔项目：

air --build.cmd "go build -o bin/api cmd/run.go" --build.bin "./bin/api" --build.exclude_dir "templates,build"

安装

通过 go install（推荐）

使用 go 1.22 或更高版本：

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

通过 install.sh

# 二进制文件将安装到 $(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

通过 goblin.run

# 二进制文件将安装到 /usr/local/bin/air
curl -sSfL https://goblin.run/github.com/air-verse/air | sh

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

Docker/Podman

请拉取此 Docker 镜像 cosmtrek/air。

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

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。

<details> <summary>示例</summary>

我的一个项目在 Docker 中运行：

docker run -it --rm \
  -w "/go/src/github.com/cosmtrek/hub" \
  -v $(pwd):/go/src/github.com/cosmtrek/hub \
  -p 9090:9090 \
  cosmtrek/air

另一个例子：

cd /go/src/github.com/cosmtrek/hub
AIR_PORT=8080 air -c "config.toml"

这将用当前目录替换 $PWD，$AIR_PORT 是要发布的端口，$@ 用于接受应用程序本身的参数，例如 -c

</details>

使用

为了减少输入，你可以在 .bashrc 或 .zshrc 中添加 alias air='~/.air'。

首先进入你的项目

cd /path/to/your_project

最简单的用法是运行

# 首先在当前目录查找 `.air.toml`，如果没有找到，则使用默认设置
air -c .air.toml

你可以使用以下命令将默认设置的 .air.toml 配置文件初始化到当前目录。

air init

之后，你可以直接运行 air 命令而无需额外参数，它将使用 .air.toml 文件进行配置。

air

要修改配置，请参考 air_example.toml 文件。

运行时参数

你可以通过在 air 命令后添加参数来传递给构建的二进制文件。

# 将运行 ./tmp/main bench
air bench

# 将运行 ./tmp/main server --port 8080
air server --port 8080

你可以使用 -- 参数来分隔传递给 air 命令和构建的二进制文件的参数。

# 将运行 ./tmp/main -h
air -- -h

# 将使用自定义配置运行 air 并将 -h 参数传递给构建的二进制文件
air -c .air.toml -- -h

Docker Compose

services:
  my-project-with-air:
    image: cosmtrek/air
    # working_dir 值必须与映射卷相同
    working_dir: /project-package
    ports:
      - <any>:<any>
    environment:
      - ENV_A=${ENV_A}
      - ENV_B=${ENV_B}
      - ENV_C=${ENV_C}
    volumes:
      - ./project-relative-path/:/project-package/

调试

air -d 打印所有日志。

不想使用 air 镜像的 Docker 用户的安装和使用方法

Dockerfile

# 选择你想要的版本，版本 >= 1.16
FROM golang:1.22-alpine

WORKDIR /app

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

COPY go.mod go.sum ./
RUN go mod download

CMD ["air", "-c", ".air.toml"]

docker-compose.yaml

version: "3.8"
services:
  web:
    build:
      context: .
      # 修正到你的 Dockerfile 的路径
      dockerfile: Dockerfile
    ports:
      - 8080:3000
    # 重要：将你的代码库目录绑定/挂载到 /app 目录以实现实时重载
    volumes:
      - ./:/app

常见问题

"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 <---- 确认这行在你的配置文件中！！！

在 wsl 下，当 bin 中包含 ' 时出错

应使用 \ 来转义 bin 中的 '。相关问题：#305

问题：如何只进行热编译而不运行任何内容？

#365

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

如何在静态文件变更时自动刷新浏览器

参考问题 #512 获取更多详情。

• 确保你的静态文件在 include_dir、include_ext 或 include_file 中。
• 确保你的 HTML 有一个 </body> 标签
• 通过配置以下设置来激活代理：

[proxy]
  enabled = true
  proxy_port = <air 代理端口>
  app_port = <你的服务器端口>

开发

请注意，由于我使用 go mod 管理依赖，所以需要 Go 1.16+ 版本。

# Fork 这个项目

# 克隆它
mkdir -p $GOPATH/src/github.com/cosmtrek
cd $GOPATH/src/github.com/cosmtrek
git clone git@github.com:<YOUR USERNAME>/air.git

# 安装依赖
cd air
make ci

# 探索它并开心地黑客吧！
make install

欢迎提交 Pull 请求。

发布

# 切换到 master 分支
git checkout master

# 添加需要发布的版本
git tag v1.xx.x

# 推送到远程
git push origin v1.xx.x

# CI 将处理并发布新版本。等待约 5 分钟，你就可以获取最新版本

Star 历史

赞助

非常感谢众多支持者。我一直铭记你们的善意。

许可证

GNU General Public License v3.0