Go プロジェクト作成からホットリロードまで

Go で新規プロジェクトを始めるときの一連の手順をまとめます。go mod init から、ビルド時のハマりどころ、air によるホットリロード環境の構築までを一気通貫で扱います。

プロジェクトの作成

新規フォルダを作って、その中で以下を実行します。

これで go.mod が生成され、モジュールとしての扱いが始まります。

go mod init 直後の go.mod を確認すると、ローカルにインストールしている Go のバージョンと違う行が書かれていることがあります。

これは Go 1.26 以降の仕様変更が原因です。go mod init は新しい go.mod に対して、実行中のツールチェーンそのものではなく 1つ前の Go バージョン を既定で書くようになりました。互換性確保のためのデフォルト挙動です。

実行中の Go バージョンに合わせたい場合は、以下のように明示的に書き換えます。

最小構成で動作確認します。

開発中はソースから直接実行するのが手軽です。

バイナリを生成して実行する場合は以下のようにします。

ここで -buildvcs=false というオプションが登場します。

-buildvcs=false は「コンパイルを雑にする」オプションではありません。 Git 情報（コミットハッシュ等）をバイナリに埋め込む処理だけを無効化するオプションです。

Git 管理下でない、もしくは Git 状態の取得に失敗する環境（CI のサンドボックス、コンテナ内など）では、このオプションを付けないとビルド時にエラーや警告が出ることがあります。

ファイル変更を検知して自動で再ビルド・再起動してくれる air を導入します。

go install でインストールしたバイナリは $(go env GOPATH)/bin に置かれます。PATH が通っていない場合は、シェルの設定に追記しておきます。

プロジェクトルートで以下を実行すると、.air.toml が生成されます。

そのままだと、先ほど触れた Git 情報の埋め込み問題で起動に失敗するケースがあります。.air.toml の cmd に -buildvcs=false を追加しておくと安全です。

# 変更前
cmd = "go build -o ./tmp/main ."
 
# 変更後
cmd = "go build -buildvcs=false -o ./tmp/main ."

あとは、

で起動すれば、ファイルを保存するたびに自動で再ビルド・再起動されるようになります。

最小構成でつまずきやすい箇所を抑えておくと、その後の開発がスムーズに進められます。