Goenv のベストプラクティス

以下は goenv のベストプラクティスまとめです（2025 年時点の推奨）。よくある落とし穴を避け、開発効率とチームの一貫性を高めます。

1. インストールと基本設定（推奨方法）


brew install goenv
// 最新の golang バージョンが見つからない場合はアップグレード
brew upgrade goenv


# 推奨: git でインストール（自動更新に対応）
git clone https://github.com/go-nv/goenv.git ~/.goenv
 
# シェルに追加（zsh または bash）
echo 'export GOENV_ROOT="$HOME/.goenv"' >> ~/.zshrc
echo 'export PATH="$GOENV_ROOT/bin:$PATH"' >> ~/.zshrc
echo 'eval "$(goenv init -)"' >> ~/.zshrc
source ~/.zshrc

Homebrew（macOS）で goenv を入れないでください。brew 版の更新は非常に遅く、多くの新しい Go バージョンに対応しません。

2. コアなベストプラクティス

シナリオ	推奨アプローチ	コマンド例
プロジェクト単位で Go バージョンを固定	各プロジェクトのルートに `.go-version` を置く（goenv がこれを最初に読む）	`goenv local 1.23.4`
チームでバージョンを揃える	`.go-version` を git にコミットし、チームが自動的に揃う	echo “1.23.4” > .go-version && git add .go-version
グローバルな既定バージョン	フォールバックを 1 つだけ設定し、特定バージョンを使わないときに使う	`goenv global 1.23.4`
一時的なバージョン切り替え	シェルで隔離し、プロジェクトに影響しない	`GOENV_VERSION=1.22.8 go run main.go` または `goenv shell 1.22.8`
現在のバージョンを確認	`go version` ではなく goenv コマンドを使う（前者はシステムの Go を読むことがある）	`goenv version` または `go version-name`

3. 推奨するバージョン管理戦略（重要！）


# 1. プロジェクトで強制指定（強く推奨。全プロジェクトで行う）
cd myproject
goenv local 1.23.4    # .go-version を自動生成
 
# 2. グローバルはよく使う安定版を 1 つだけ（任意）
goenv global 1.23.4
 
# 3. システムの Go に頼らない（macOS / Linux ディストリビューション版は非常に古い）

4. 他ツールとの連携のベストプラクティス

ツール	推奨設定
direnv	強く推奨。`.envrc` で `layout go` または `use goenv` を自動読み込み
asdf	asdf と goenv で同時に Go を管理しない。衝突しやすいので goenv だけ使う
docker	Dockerfile では公式 golang イメージを使い、ホストの goenv に依存しない
vscode	Go プラグイン導入後、`.go-version` を自動認識。追加設定は不要

direnv の例（強力な組み合わせ）:


# .envrc
use goenv
layout go   # プロジェクト隔離用の gopath bin を自動作成

5. よくある落とし穴と対処

問題	解決策
`go: command not found`	`eval "$(goenv init -)"` が実行されたか確認し、ターミナルを開き直すか source する
新しい Go を入れたのに `go version` が古い	PATH の前方にシステムの Go がある可能性。`goenv init -` を PATH の先頭に置く
go mod download が遅い	GOPROXY を設定（goenv とは無関係だがよく併用） `go env -w GOPROXY=https://goproxy.cn,direct`
複数プロジェクト間の切り替えが面倒	direnv + .go-version で自動切り替え

6. 推奨する完全な ~/.zshrc 設定スニペット（2025 年版）


export GOENV_ROOT="$HOME/.goenv"
export PATH="$GOENV_ROOT/bin:$PATH"
eval "$(goenv init -)"
export PATH="$GOROOT/bin:$PATH"
export PATH="$PATH:$GOPATH/bin"
 
# 中国向け加速（強く推奨）
export GOPROXY=https://goproxy.cn,direct
export GOSUMDB=sum.golang.google.cn

例外処理


// 一部のエディタは GOPATH 環境変数をキャッシュすることがある。終了して再読み込み
vscode quit

vscode との連携

vscode の Go プラグインの分析ツールを更新し、すべて選択して再インストールします

キャッシュのクリア

Go には複数のキャッシュディレクトリがあります


go clean cache

まとめ：黄金ルール（これを覚える）

すべてのプロジェクトルートに .go-version を置く（git にコミット）
グローバルバージョンはフォールバックを 1 つだけ
direnv で自動切り替え（効率が倍になる）
システムの Go に頼らない
プロジェクトバージョンは goenv shell ではなく goenv local で設定する

以上に従えば、Go のバージョン管理でほぼ躓かず、チーム協業も非常にスムーズです。楽しんでください。