Next.js × AWS(ECS/Fargate) × GitHub Actionsで学んだyarn.lock運用術

Next.js × AWSデプロイでチーム開発しているなら、yarn.lock をGit管理すべき理由と運用ルール

結論

Next.jsアプリをAWSにデプロイしているチーム開発では、
yarn.lock を必ずGit管理に含め、CI/CDでロックファイルを尊重する運用が必須です。

理由はシンプルで、

• 本番とローカルで依存関係がズレない
• 「昨日まで動いてたのに今日突然壊れた」を防げる
• チーム全員で同じ環境を再現できる
  からです。

背景

• チーム人数：約10人
• デプロイ先：AWS ECS/Fargate
• フレームワーク：Next.js（SSR前提）
• パッケージマネージャー：Yarn

この環境で「yarn.lock をコミットする？しない？」が人によってバラバラでした。
結果、ローカルと本番で「お前…誰だ？」状態の依存が混ざり、SSR界隈がカオス化。

実際に遭遇したカオス例

• Hydration mismatch地獄
  ローカル: react-dom@18.2.0
  本番: react-dom@18.3.0
  → ビルドは通るが、画面を開くと赤文字エラーが爆誕。「おまえ昨日まで仲良くしてただろ！」状態。

• 突然のCI爆死
  CIサーバーで yarn install → 新しい依存が勝手に入る → next build 爆散。
  ローカルで「俺のマシンでは動く」発言が乱発され、プロジェクトは一時休止。

• 謎のライブラリアップデート祭り
  ^1.2.3 みたいなバージョン指定で、デプロイ時に最新を勝手に拾う。
  まるで「ガチャを引くたびに依存が進化する」仕様。SSRガチャは心臓に悪い。

解決方法（運用ルール）

1. yarn.lock をGit管理に必ず含める
2. Node/Yarnのバージョンを固定（.node-versionやengines）
3. CI/CDではロックファイルを尊重
   • Yarn v1 → yarn install --frozen-lockfile
   • Yarn Berry → yarn install --immutable
4. 依存更新はPR経由のみ（Renovateなど導入推奨）
5. 競合時は再生成で解決（手でyarn.lockを編集しない）

GitHub Actions 実装例

CI

jobs:
  build-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '18.20.4'
          cache: 'yarn'
      - run: corepack enable
      - run: yarn install --immutable   # lock尊重
      - run: yarn build
      - run: yarn test --ci

ECSデプロイ（抜粋）

  deploy-ecs:
    needs: build-test
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::<ACCOUNT_ID>:role/github-oidc-deploy-role
          aws-region: ap-northeast-1
      - uses: aws-actions/amazon-ecr-login@v2
      - run: |
          docker build -t $ECR_URI:$GITHUB_SHA .
          docker push $ECR_URI:$GITHUB_SHA
      - run: |
          aws ecs update-service             --cluster my-cluster             --service my-service             --force-new-deployment             --task-definition my-task

Dockerfile（依存キャッシュ効かせるパターン）

FROM node:18.20-bullseye AS deps
WORKDIR /app
COPY package.json yarn.lock ./
RUN corepack enable && yarn install --immutable

FROM node:18.20-bullseye AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN yarn build

FROM node:18.20-bullseye AS runner
WORKDIR /app
ENV NODE_ENV=production
COPY --from=builder /app ./
EXPOSE 3000
CMD ["yarn","start"]

まとめ

• Next.jsアプリをAWSにデプロイするなら、yarn.lockはGit管理必須
• CI/CDで --immutable / --frozen-lockfile を強制して、依存のズレを完全に防ぐ
• Node/Yarnのバージョンも固定して、再現性を最大化する
• 依存更新は必ずPR経由にしてレビュー可能にする

最後に

依存地獄に落ちると、本番環境が「毎日新しいバグを配信するガチャ」みたいになってしまいます。
オタク風に言えば、**ロックファイルは異世界転生モノの「セーブポイント」**です。これを捨てるのは無謀。

チームで「お前またlockファイル無視しただろ！」というバトルを減らし、
安定したSSRライフを楽しむために、ぜひyarn.lockをコミットしましょう。