この記事の要点

go build は Go のソースコードを実行可能バイナリにコンパイルするコマンド（インストールはせず生成だけ） 出力先は -o、リンクフラグは -ldflags、ビルドタグは -tags、詳細表示は -v GOOS/GOARCH 環境変数でクロスコンパイルが可能（例: Linux 上で Windows 用 exe を生成） 依存解決は go.mod / go.sum を使う Go Modules ベース。GOPATH モードは旧式 生成物を作らず構文・型チェックだけしたいときは go vet や go build ./... + キャッシュ確認が定番

go build とは

go build は Go のツールチェインに付属する標準コマンドで、ソースコード（.go ファイル）を実行可能なバイナリに変換します。コマンド・ディレクティブ一覧 の中でも、go run と並んで開発中もっとも頻繁に使うコマンドです。

似たコマンドとの違いを整理します。

コマンド	動作	使い所
go build	バイナリをカレントディレクトリに生成	配布・本番用ビルド、CI でのアーティファクト作成
go run	テンポラリにビルドして即実行（バイナリは残さない）	動作確認、スクリプト的な使い方
go install	ビルド後 $GOBIN（通常 $GOPATH/bin）に配置	CLI ツールを PATH 通った場所に置きたいとき
go test	テストバイナリをビルドして実行	ユニットテスト・ベンチマーク

基本構文

# 1. 現在のディレクトリの main パッケージをビルド（カレントに実行ファイル生成）
go build

# 2. 出力ファイル名を指定
go build -o myapp

# 3. サブディレクトリ配下のパッケージをまとめてビルド
go build ./...

# 4. 特定のパッケージパス（モジュール内パス）を指定
go build ./cmd/server

# 5. 単一ファイルをビルド（main 関数を含む .go ファイル）
go build main.go

第 1 形式 go build を main パッケージのルートで実行すると、モジュール名（go.mod の module 行の末尾セグメント）を名前にしたバイナリが生成されます。Windows では .exe 拡張子が付きます。

主要オプション

頻出オプションをまとめます。すべてのオプションは go help build で確認できます。

オプション	意味	例
-o <file>	出力ファイル名（パス指定可）	go build -o bin/myapp
-v	コンパイルしたパッケージ名を表示	go build -v ./...
-x	内部で実行されるコマンドを全部表示（デバッグ用）	go build -x
-race	レースディテクタを有効にしてビルド	go build -race
-tags <list>	ビルドタグを有効化（条件付きコンパイル）	go build -tags "prod cgo"
-ldflags "..."	リンカに渡すフラグ（変数注入・サイズ削減など）	下記サンプル参照
-gcflags "..."	コンパイラに渡すフラグ（最適化・デバッグ）	-gcflags "all=-N -l" でデバッガ用
-trimpath	バイナリにフルパスを埋め込まない（再現性確保）	go build -trimpath
-mod=<mode>	モジュールモード切替（mod / readonly / vendor）	go build -mod=vendor

-o による出力先指定

# 単一ファイル名を指定
go build -o myapp

# サブディレクトリに置く（ディレクトリは事前に作っておく）
mkdir -p bin
go build -o bin/myapp

# Windows 用 exe
go build -o bin/myapp.exe

-o で末尾がスラッシュのディレクトリを指定すると、そのディレクトリに既定のバイナリ名で出力されます。CI でアーティファクトをまとめるときに便利です。

-ldflags でバージョン情報を埋め込む

本番ビルドではバイナリに「リビジョン・ビルド日時」などを埋め込んでおくと、運用時の追跡が楽になります。-ldflags "-X" でパッケージ変数に文字列を注入します。

// main.go
package main

import "fmt"

var (
    Version   = "dev"
    GitCommit = "unknown"
    BuildDate = "unknown"
)

func main() {
    fmt.Printf("version=%s commit=%s built=%s\n", Version, GitCommit, BuildDate)
}

VERSION=1.0.0
COMMIT=$(git rev-parse --short HEAD)
DATE=$(date -u +%Y-%m-%dT%H:%M:%SZ)

go build -ldflags "-X main.Version=${VERSION} -X main.GitCommit=${COMMIT} -X main.BuildDate=${DATE}" -o myapp

さらにバイナリサイズを削りたい場合は -ldflags "-s -w" を併用するとシンボルテーブルと DWARF デバッグ情報が落ちて、数 MB 単位で軽くなることがあります。デバッガでのスタックトレース解析が困難になる点だけ注意してください。

-tags でビルドタグを切り替える

ファイル先頭に //go:build prod のようなディレクティブを書くと、そのタグが指定されたときだけそのファイルをコンパイル対象にできます。環境別の設定切り替えなどに使います。

//go:build prod

package config

const Endpoint = "https://api.example.com"

go build -tags prod -o myapp

クロスコンパイル

Go の大きな魅力の 1 つが、追加ツール無しでクロスコンパイル可能なこと。GOOS と GOARCH を切り替えるだけで他 OS / アーキ向けのバイナリが作れます。

環境変数	値の例
GOOS	linux / darwin / windows / freebsd / android
GOARCH	amd64 / arm64 / 386 / arm / riscv64
CGO_ENABLED	クロスコンパイル時は 0 が無難（C 依存を持ち込まない）

# Linux (x86_64) 上で Windows (amd64) 用バイナリを作る
GOOS=windows GOARCH=amd64 go build -o myapp.exe

# macOS (Apple Silicon) 向け
GOOS=darwin GOARCH=arm64 go build -o myapp-darwin-arm64

# Raspberry Pi 向け
GOOS=linux GOARCH=arm GOARM=7 go build -o myapp-armv7

# 利用可能な OS / アーキ一覧
go tool dist list

ビルドキャッシュ

Go は変更されていないパッケージのコンパイル結果を $GOCACHE（既定で ~/.cache/go-build）にキャッシュします。二回目以降のビルドが速いのはこれが効いているためです。

# キャッシュ場所
go env GOCACHE

# キャッシュをクリア（不整合っぽい挙動のときに試す）
go clean -cache

# モジュールキャッシュもクリア
go clean -modcache

よくあるエラーと対処

症状	原因 / 対処
go: cannot find main module	go.mod が見当たらない。リポジトリのルートで go mod init <モジュール名> を実行
package XXX is not in std	外部パッケージを import しているのに依存が解決されていない。go mod tidy で go.mod / go.sum を更新
undefined: main.foo	main パッケージから参照している関数や変数が存在しない／別ファイルで定義しているのに go build 引数が単一ファイル指定になっている
build constraints exclude all Go files	すべてのファイルがビルドタグや GOOS/GOARCH 条件で除外された。タグ指定や対象 OS を見直す
missing go.sum entry	依存先のチェックサムが go.sum に記録されていない。go mod download または go mod tidy
クロスビルドで gcc: command not found	cgo を要求するパッケージを含んでいる。CGO_ENABLED=0 を付けるか、対象 OS 向けクロスコンパイラを用意する

関連

• Go — 言語本体の解説
• コマンド・ディレクティブ一覧 — go コマンドの全体俯瞰