Go Modules（go.mod）の依存の追加・更新・確認・削除を中心に、実務でよく使うコマンドと運用方法をまとめました。
0) 初期化・基本
# 新規モジュール作成（ルートで）
go mod init example.com/your/module
# 依存解決・不要な行の整理（よく使う）
go mod tidy
# 依存を事前にダウンロード（CI のウォームアップなど）
go mod download
# モジュールの整合性チェック（go.sum の検証）
go mod verify
1) 依存の 追加
A. コードに import してから解決
# 例：それぞれのコードに `import "github.com/aws/aws-sdk-go-v2/config"` を書いた後
go get github.com/aws/aws-sdk-go-v2/config@latest
go mod tidy
B. 直接 go get
# 例：AWS SDK v2 の Secrets Manager クライアント
go get github.com/aws/aws-sdk-go-v2/service/secretsmanager@latest
go mod tidy
2) 依存の 更新
単体モジュールを更新
# そのモジュールの最新リリースへ（メジャー含む）
go get example.com/mod@latest
# パッチのみ（互換更新）：マイナー・メジャーを上げない
go get -u=patch example.com/mod
# マイナーまで（メジャーは維持）：よく使う
go get -u example.com/mod
一括更新（慎重に）
# すべてパッチのみ
go get -u=patch ./...
# すべてマイナーまで（メジャーは維持）
go get -u ./...
特定のコミット/タグへピン止め
# タグ
go get example.com/mod@v1.2.3
# コミット（擬似バージョンに解決される）
go get example.com/mod@abcdef1234
MVS（Minimal Version Selection）
Go は「必要最小のバージョン」を選ぶため、直接指定していない限りトランジティブ依存は勝手に最新化されません。
依存の上げ忘れに気づきにくい反面、再現性は高いです。
3) 依存の 確認（可視化・調査）
# 使っているモジュール一覧
go list -m all
# アップデート可能な最新（マイナー/パッチ）を表示
go list -m -u all
# JSON で詳細（jq などと併用）
go list -m -u -json all | jq '.'
# なぜこの依存が入ったの？（依存経路を表示）
go mod why -m example.com/mod
# 依存グラフ（テキスト）
go mod graph
4) 依存の 削除
使っていない import を消してから整理
# まずコードから import を削除
# その後、不要条項を go.mod/go.sum から整理
go mod tidy
強制的に要件から外す
go get example.com/mod@none
go mod tidy
5) replace / exclude（ピン/差し替え/除外）
replace: フォークやローカル、特定コミットに差し替え
// go.mod
replace example.com/upstream => github.com/yourfork/upstream v1.2.3
# or ローカルパス
replace example.com/upstream => ../upstream
# 追加・削除（コマンドで）
go mod edit -replace=example.com/upstream=../upstream
go mod edit -dropreplace=example.com/upstream
注意: ローカル
replaceは CI/ビルドで壊れやすいので、コミット前に外すのが鉄則。
exclude: 問題のある特定バージョンを使わせない
exclude example.com/mod v1.4.2
6) メジャーバージョンの上げ方（v2+）
-
importパスに/v2のように メジャー番号を含める必要あり（Semantic Import Versioning） - 例）
module example.com/appからgithub.com/foo/bar/v2を使う場合：
import "github.com/foo/bar/v2/pkg"
go get github.com/foo/bar/v2@v2.3.1
go mod tidy
7) ツール類のバージョン管理（CI 再現性）
go install（推奨）
# ツールはプロジェクト依存に入れない（go.mod 化しない）
go install github.com/golangci/golangci-lint/cmd/golangci-lint@v1.64.2
go install entgo.io/ent/cmd/ent@v0.14.4
8) Vendor 運用（必要なら）
# vendor ディレクトリを作成
go mod vendor
# vendor を使ってビルド
go build -mod=vendor ./...
- Pros: 完全再現、ネットワーク不要
- Cons: リポジトリが重くなる、更新負荷
- 使うなら CI でも
-mod=vendorを徹底（中途半端が一番危険かも）
9) キャッシュやエラー時の対処
# モジュールキャッシュをクリア（破損/整合性エラー時）
go clean -modcache
# GOPROXY を確認/上書き（社内プロキシや切り替え時）
go env GOPROXY
go env -w GOPROXY=https://proxy.golang.org,direct
# プライベートモジュールがある場合
go env -w GOPRIVATE=github.com/your-org/*
-
checksum mismatchが出たら：go clean -modcache→go mod downloadを試す - プライベート依存は
GOPRIVATE設定＋gitの資格情報が必要
10) CI でのおすすめフロー
- run: go version
- run: go env
- run: go mod tidy
- run: git diff --exit-code go.mod go.sum # ここで差分あれば fail（手元で tidy を忘れてる）
- run: go build ./...
- run: go test ./... -cover
11) その他メモ
-
indirect は
go mod tidyが自動で適切に整えてくれているので、手で消さない。 -
go get -u allは 大規模プロジェクトでは破壊的になり得る。 -
まずは
go list -m -u allで確認 → 個別更新すべき。 -
“undefined: X” や “missing go.sum entry” が出る場合
go getで必要なモジュールを追加し、go mod tidy。
Sum が壊れたらgo clean -modcache。