{ "componentChunkName": "component---src-templates-issues-tsx", "path": "/issues/16", "result": {"data":{"issuesJson":{"id":"b2693c3e-6f51-5022-bfab-064fd1f70633","title":"cosmtrek/air: ☁️ 针对 Golang 应用开发设计的一个热重载的命令行工具","number":16,"bodyHTML":"
\n



\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Reposcosmtrek/air
Views\"views\"
Stars\"stars\"
Forks\"forks\"
License\"license\"
UpdatedAt\"last-commit\"
CreatedAt\"create-at\"
\n\n

\"\"

\n\n
\n

☁️ Air - Live reload for Go apps

\n

\"Go\" \"Codacy \"Go \"codecov\"

\n

\"air\"

\n

English | 简体中文 | 繁體中文 | 日本語

\n

Motivation

\n

When I started developing websites in Go and using gin framework, it was a pity
\nthat gin lacked a live-reloading function. So I searched around and tried fresh, it seems not much
\nflexible, so I intended to rewrite it better. Finally, Air's born.
\nIn addition, great thanks to pilu, no fresh, no air :)

\n

Air is yet another live-reloading command line utility for developing Go applications. Run air in your project root directory, leave it alone,
\nand focus on your code.

\n

Note: This tool has nothing to do with hot-deploy for production.

\n

Features

\n\n

Overwrite specify configuration from arguments

\n

Support air config fields as arguments:

\n

You can view the available command-line arguments by running the following commands:

\n
air -h\n
\n

or

\n
air --help\n
\n

If you want to config build command and run command, you can use like the following command without the config file:

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

Use a comma to separate items for arguments that take a list as input:

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

Installation

\n

Via go install (Recommended)

\n

With go 1.23 or higher:

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

Via install.sh

\n
# binary will be $(go env GOPATH)/bin/air\ncurl -sSfL https://raw.githubusercontent.com/air-verse/air/master/install.sh | sh -s -- -b $(go env GOPATH)/bin\n\n# or install it into ./bin/\ncurl -sSfL https://raw.githubusercontent.com/air-verse/air/master/install.sh | sh -s\n\nair -v
\n

Via goblin.run

\n
# binary will be /usr/local/bin/air\ncurl -sSfL https://goblin.run/github.com/air-verse/air | sh\n\n# to put to a custom path\ncurl -sSfL https://goblin.run/github.com/air-verse/air | PREFIX=/tmp sh
\n

Docker/Podman

\n

Please pull this Docker image cosmtrek/air.

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

Docker/Podman .${SHELL}rc

\n

if you want to use air continuously like a normal app, you can create a function in your ${SHELL}rc (Bash, Zsh, etc…)

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

<PROJECT> is your project path in container, eg: /go/example
\nif you want to enter the container, Please add --entrypoint=bash.

\n
\n For example\n

One of my project runs in Docker:

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

Another example:

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

this will replace $PWD with the current directory, $AIR_PORT is the port where to publish and $@ is to accept arguments of the application itself for example -c

\n
\n

Usage

\n

For less typing, you could add alias air='~/.air' to your .bashrc or .zshrc.

\n

First enter into your project

\n
cd /path/to/your_project
\n

The simplest usage is run

\n
# firstly find `.air.toml` in current directory, if not found, use defaults\nair -c .air.toml
\n

You can initialize the .air.toml configuration file to the current directory with the default settings running the following command.

\n
air init
\n

After this, you can just run the air command without additional arguments, and it will use the .air.toml file for configuration.

\n
air
\n

For modifying the configuration refer to the air_example.toml file.

\n

Runtime arguments

\n

You can pass arguments for running the built binary by adding them after the air command.

\n
# Will run ./tmp/main bench\nair bench\n\n# Will run ./tmp/main server --port 8080\nair server --port 8080
\n

You can separate the arguments passed for the air command and the built binary with -- argument.

\n
# Will run ./tmp/main -h\nair -- -h\n\n# Will run air with custom config and pass -h argument to the built binary\nair -c .air.toml -- -h
\n

Docker Compose

\n
services:\n  my-project-with-air:\n    image: cosmtrek/air\n    # working_dir value has to be the same of mapped volume\n    working_dir: /project-package\n    ports:\n      - <any>:<any>\n    environment:\n      - ENV_A=${ENV_A}\n      - ENV_B=${ENV_B}\n      - ENV_C=${ENV_C}\n    volumes:\n      - ./project-relative-path/:/project-package/
\n

Debug

\n

air -d prints all logs.

\n

Installation and Usage for Docker users who don't want to use air image

\n

Dockerfile

\n
# Choose whatever you want, version >= 1.16\nFROM golang:1.23-alpine\n\nWORKDIR /app\n\nRUN go install github.com/air-verse/air@latest\n\nCOPY go.mod go.sum ./\nRUN go mod download\n\nCMD [\"air\", \"-c\", \".air.toml\"]
\n

docker-compose.yaml

\n
version: \"3.8\"\nservices:\n  web:\n    build:\n      context: .\n      # Correct the path to your Dockerfile\n      dockerfile: Dockerfile\n    ports:\n      - 8080:3000\n    # Important to bind/mount your codebase dir to /app dir for live reload\n    volumes:\n      - ./:/app
\n

Q&A

\n

\"command not found: air\" or \"No such file or directory\"

\n
export GOPATH=$HOME/xxxxx\nexport PATH=$PATH:$GOROOT/bin:$GOPATH/bin\nexport PATH=$PATH:$(go env GOPATH)/bin #Confirm this line in your .profile and make sure to source the .profile if you add it!!!
\n

Error under wsl when ' is included in the bin

\n

Should use \\ to escape the ' in the bin. related issue: #305

\n

Question: how to do hot compile only and do not run anything?

\n

#365

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

How to Reload the Browser Automatically on Static File Changes

\n

Refer to issue #512 for additional details.

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

Development

\n

Please note that it requires Go 1.16+ since I use go mod to manage dependencies.

\n
# Fork this project\n\n# Clone it\nmkdir -p $GOPATH/src/github.com/cosmtrek\ncd $GOPATH/src/github.com/cosmtrek\ngit clone git@github.com:<YOUR USERNAME>/air.git\n\n# Install dependencies\ncd air\nmake ci\n\n# Explore it and happy hacking!\nmake install
\n

Pull requests are welcome.

\n

Release

\n
# Checkout to master\ngit checkout master\n\n# Add the version that needs to be released\ngit tag v1.xx.x\n\n# Push to remote\ngit push origin v1.xx.x\n\n# The CI will process and release a new version. Wait about 5 min, and you can fetch the latest version
\n

Star History

\n

\"Star

\n

Sponsor

\n

\"Buy

\n

Give huge thanks to lots of supporters. I've always been remembering your kindness.

\n

License

\n

GNU General Public License v3.0

","updatedAt":"2025-05-21T15:48:03Z","upvoteCount":null,"author":{"login":"eryajf","avatarUrl":"https://avatars.githubusercontent.com/u/33259379?u=e4a4090a38ac2473aaed4ef9945233636776c6c3&v=4","url":"https://github.com/eryajf"},"category":null,"labels":{"edges":[{"node":{"name":"更多","color":"25B472"}},{"node":{"name":"Dev-Tools","color":"48310b"}},{"node":{"name":"cosmtrek","color":"eee227"}}]},"comments":{"edges":[]}}},"pageContext":{"number":16,"previous":{"title":"airbytehq/airbyte: 一个开源数据集成引擎，可帮助您整合数据仓库、数据湖和数据库中的数据。","number":15},"next":{"title":"akile-network/akile_monitor: 一个简洁的服务器监控面板，提供了一些基础信息的监控。","number":17}}}, "staticQueryHashes": ["151096407","2861350382"]}