エラーの理解
go: inconsistent vendoring エラーは、go.mod ファイルと vendor/ ディレクトリが同期されていない場合に発生します。vendor フォルダが存在する場合、最近の Go バージョン（vendor フォルダがあればデフォルトで有効）では -mod=vendor フラグが使用され、Go ツールチェーンは vendor/modules.txt をチェックして go.mod で定義されている内容と一致するか確認します。
go.mod に新しい依存関係を追加したのに vendor ディレクトリの更新を忘れた場合や、Git のマージによって不整合が生じた場合、Go は誤った、あるいは不足しているソースコードでビルドされるのを防ぐためにビルドを停止し、このエラーを表示します。
go: inconsistent vendoring in /app:
github.com/foo/bar@v1.2.3: is explicitly required in go.mod, but not marked as explicit in vendor/modules.txt
ステップバイステップの修正方法
ステップ 1: 依存関係の同期
最も一般的な原因は、新しいパッケージを追加した後に vendor コマンドの実行を忘れていることです。プロジェクトのルートで以下のコマンドを実行してください。
# 未使用の依存関係を削除し、不足しているものを go.mod に追加
go mod tidy
# go.mod と一致するように vendor ディレクトリを更新
go mod vendor
go mod vendor コマンドは vendor/ フォルダを書き換え、vendor/modules.txt を再生成します。これにより不整合が解消されるはずです。
ステップ 2: Git マージコンフリクトの確認
最近ブランチをマージした場合、go.mod は更新されたが vendor/modules.txt が更新されていない（あるいはその逆）可能性があります。go mod vendor で即座に解決しない場合は、一旦 vendor フォルダを完全に削除してから再作成してみてください。
rm -rf vendor/
go mod tidy
go mod vendor
ステップ 3: Docker 内の不整合を修正する
このエラーがローカルマシンではなく Docker コンテナ内で発生する場合は、Dockerfile を確認してください。よくあるケースとして、開発者が go.mod と go.sum はコピーしているものの vendor フォルダのコピーを忘れていたり、環境が vendor ディレクトリを使用するように設定されているのにコンテナが依存関係をダウンロードすることを前提に go build を実行していたりすることがあります。
vendor ディレクトリを使用する構成にしている場合は、Dockerfile で確実にコピーされるようにしてください。
# Dockerfile のスニペット例
COPY go.mod go.sum ./
COPY vendor/ vendor/
RUN go build -mod=vendor -o myapp
あるいは、Docker 内で vendor フォルダを使用したくない場合は、.dockerignore で vendor ディレクトリを除外し、-mod=vendor フラグを使用しないように設定してください。
ステップ 4: Go バージョンの確認
Go のバージョンによって、ベンダー管理の扱いが異なる場合があります。go mod vendor を実行した Go のバージョンと、アプリケーションのビルドに使用しているバージョンが一致していることを確認してください。バージョンは以下のコマンドで確認できます。
go version
検証：修正が機能したか確認する方法
不整合が解消されたことを確認するには、vendor ディレクトリの使用を明示的に強制してビルドコマンドを実行します。
go build -mod=vendor ./...
コマンドが何も出力せずに完了すれば、vendor/modules.txt ファイルは go.mod と正しく同期されています。また、エラーメッセージに記載されていた不足パッケージが vendor/modules.txt に含まれていることも確認できるはずです。
このエラーを回避するためのプロのヒント
- CI/CD チェック: CI パイプラインに
go mod tidyとgo mod vendorを実行し、その後git status --porcelainが空であることを確認するステップを追加します。これにより、更新された vendor フォルダのコミット漏れを確実に防げます。 - Go 環境: 実際に
vendorフォルダが必要ない場合は、削除を検討してください。Go Modules は、ローカルのvendorディレクトリがなくても、モジュールキャッシュ ($GOPATH/pkg/mod) に依存関係をダウンロードすることで正常に動作します。 - 読み取り専用フラグ: ビルド環境では
go build -mod=readonlyを使用してください。これにより、go.modの更新が必要な場合にファイルをサイレントに変更するのではなく、ビルドを失敗させることができます。