過去バージョン

Go Modules の全体像

Go 1.11+ の標準パッケージ管理が Go Modules。$GOPATH から解放され、プロジェクト単位で依存を管理します。

初期化からビルドまで

# 1. プロジェクト作成
mkdir myapp && cd myapp

# 2. モジュール初期化（モジュール名は import パス。リポジトリ URL 推奨）
go mod init github.com/myname/myapp
# → go.mod 生成

# 3. コードを書く
cat > main.go <<'EOF'
package main

import (
    "fmt"
    "github.com/google/uuid"
)

func main() {
    fmt.Println(uuid.New())
}
EOF

# 4. ビルド (自動的に依存を解決して go.mod / go.sum 更新)
go build
# go: finding module for package github.com/google/uuid
# go: downloading github.com/google/uuid v1.6.0
# go: added github.com/google/uuid v1.6.0

go.mod / go.sum の中身

// go.mod
module github.com/myname/myapp

go 1.22

require (
    github.com/google/uuid v1.6.0
    github.com/gin-gonic/gin v1.9.1
)

require (
    // 間接依存（直接 import していないが、依存先が必要としている）
    github.com/bytedance/sonic v1.9.1 // indirect
    github.com/gin-contrib/sse v0.1.0 // indirect
)

# go.sum
# パッケージごとの暗号学的ハッシュ（改ざん検知用）
github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=

両方とも Git にコミットします。vendor/ をコミットするかはチームの方針次第。

go mod download の正確な意味

# go.mod に書かれた依存をローカルキャッシュへダウンロード
go mod download

# 特定モジュールのみ
go mod download github.com/google/uuid

# JSON 形式で詳細表示
go mod download -x -json github.com/google/uuid
# {
#   "Path": "github.com/google/uuid",
#   "Version": "v1.6.0",
#   "Info": "/root/go/pkg/mod/cache/download/...",
#   "GoMod": "/root/go/pkg/mod/cache/download/...",
#   "Zip": "/root/go/pkg/mod/cache/download/...",
#   "Dir": "/root/go/pkg/mod/github.com/google/uuid@v1.6.0"
# }

キャッシュ先は $GOPATH/pkg/mod（既定 ~/go/pkg/mod）。CI で事前にダウンロードしておけば本ビルドが速い:

# Dockerfile - 依存だけ先にキャッシュ層に焼く
FROM golang:1.22 AS builder
WORKDIR /app

# go.mod / go.sum だけコピーして DL (この層は依存変更時のみ無効化)
COPY go.mod go.sum ./
RUN go mod download

# ソースを後からコピー (ソース変更で DL し直さない)
COPY . .
RUN go build -o /app/myapp ./...

FROM gcr.io/distroless/base
COPY --from=builder /app/myapp /
ENTRYPOINT ["/myapp"]

go mod tidy（コミット前必須）

# 1. 未使用の依存を go.mod / go.sum から削除
# 2. import されているが go.mod に無いものを追加
# 3. indirect マークを適切に整理
go mod tidy

# 詳細出力
go mod tidy -v

# Go バージョンを指定 (Go 1.17+ で graph 簡略化動作変更)
go mod tidy -compat=1.17

CI で「go mod tidy 後に差分が出ないこと」をチェックする運用が一般的:

# .github/workflows/ci.yml
- name: Check go mod tidy
  run: |
    go mod tidy
    git diff --exit-code go.mod go.sum

go mod vendor（オフラインビルド）

# vendor ディレクトリに依存をコピー
go mod vendor
# → vendor/ 配下に全依存のソース

# ビルド時に自動で vendor を使用 (Go 1.14+)
go build

# 明示的に vendor を使う場合
go build -mod=vendor

# vendor を使わずに module キャッシュを使う
go build -mod=mod

用途:

• オフライン環境でビルドしたい（インターネット遮断ネットワーク）
• CI のビルドを高速化（DL せず vendor からビルド）
• 依存ライブラリのソースをコードレビューしたい

GOPRIVATE / GONOPROXY / GONOSUMCHECK

社内 GitHub Enterprise 等のプライベートリポジトリを使う場合、公開 proxy (proxy.golang.org) や sum DB (sum.golang.org) を経由するとアクセス失敗します:

# プライベートとして扱うパターン（ワイルドカード可）
export GOPRIVATE='git.company.com/*,*.internal.example.com'

# proxy を使わないパターン
export GONOPROXY=$GOPRIVATE

# sum DB チェックをスキップ
export GONOSUMCHECK=$GOPRIVATE

# .gitconfig で SSH 強制（HTTPS だと認証で詰まりがち）
git config --global url."git@git.company.com:".insteadOf "https://git.company.com/"

GOPROXY: モジュールプロキシ

# 既定: 公式 proxy → 直接
go env GOPROXY
# https://proxy.golang.org,direct

# 中国向けミラー
export GOPROXY=https://goproxy.cn,direct

# 社内 Athens プロキシ
export GOPROXY=https://athens.company.com,https://proxy.golang.org,direct

# 完全に proxy 無効（直接 git clone）
export GOPROXY=direct

# off で DL 完全禁止（cache だけ使う）
export GOPROXY=off

go.mod の replace ディレクティブ

依存先をローカルパスや別バージョンに差し替えたいとき:

// go.mod
module github.com/myname/myapp

go 1.22

require (
    github.com/somepkg/lib v1.2.3
)

// ローカル開発中のライブラリを使う
replace github.com/somepkg/lib => ../lib

// フォーク版を使う
replace github.com/somepkg/lib => github.com/myname/lib v1.2.3-fork

// バージョン指定
replace github.com/somepkg/lib v1.2.3 => github.com/somepkg/lib v1.2.4

メジャーバージョン v2+ の扱い

Go Modules のセマンティックインポート規則: v2 以上はモジュールパスに /v2 を付けます:

// v1
import "github.com/foo/bar"

// v2 以上
import "github.com/foo/bar/v2"
import "github.com/foo/bar/v3"

これにより同一プロジェクト内で v1 と v2 を共存可能（移行期間用）。

go mod why（依存の根拠）

go mod why github.com/bytedance/sonic
# # github.com/bytedance/sonic
# github.com/myname/myapp
# github.com/gin-gonic/gin
# github.com/bytedance/sonic
# → gin が間接的に sonic を必要としている、と判明

# モジュール単位で
go mod why -m github.com/bytedance/sonic

よくあるトラブル

FAQ

Q: go mod download と go mod tidy はどう違う？
A: download は 記載済依存の DL のみ。tidy は go.mod 自体を整理（追加 / 削除）します。

Q: vendor ディレクトリは Git にコミットすべき？
A: 賛否両論。コミットする派: ビルド完全再現、オフライン安心。しない派: リポジトリが肥大。CI で go mod download で済むなら不要。

Q: GOPATH モードに戻したい
A: GO111MODULE=off で旧モードに。ただし Go 1.16+ では modules モードが既定でほぼ非対応の道。