Zenn
🐷

Next.jsで作ったアプリケーションをGoogle Cloud Runにデプロイする場合の注意点

2025/04/15に公開
Docker
Next.js
Cloud Run
Cloud Build
gcloud
tech

はじめに

Next.js アプリケーションのデプロイ先としては、一般的には Vercel が第一候補となるかと思います

しかし、Firebase Authentication などの Google Cloud サービスとの連携や、複数のマイクロサービスをまとめてデプロイしたい場合は、Google Cloud Run も選択肢となり得るかと思います

本記事では備忘録として、Next.js で作ったアプリケーション Cloud Run にデプロイする際の環境変数について残しておきます

ビルド時とデプロイ時の環境変数の違い

Next.js は、ビルド時に環境変数を読み込み、その値をクライアントサイドのコードに静的に埋め込む
ビルドの段階でこれらの値がコンパイル済みのバンドルに含まれるため、クライアントサイドで動作する_NEXT_PUBLIC系の環境変数は、ビルド後に環境変数を変更しても反映されない

cloud runのデプロイサンプルではgcloud runの時に環境変数を注入するケースが多いが、ビルド段階で埋め込む必要がある

ビルド＆デプロイフローのサンプル

以下は、GitHub Actions を利用して Next.js アプリケーションを Cloud Run に自動デプロイするためのサンプル

name: Deploy Web to Cloud Run

on:
  push:
    branches:
      - main
  workflow_dispatch:

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@v3

      - name: Authenticate with Google Cloud
        uses: google-github-actions/auth@v1
        with:
          credentials_json: ${{ secrets.GCP_SERVICE_ACCOUNT_KEY }}

      - name: Configure gcloud
        run: |
          gcloud config set project ${{ secrets.GCP_PROJECT_ID }}
          gcloud auth configure-docker asia.gcr.io

      - name: Build & Push Docker image
        run: |
          gcloud builds submit --config=web/cloudbuild.yaml ./ \
          --substitutions _NEXT_PUBLIC_FIREBASE_PROJECT_ID=${{ secrets.GCP_PROJECT_ID }},\
_NEXT_PUBLIC_FIREBASE_API_KEY=${{ secrets.FIREBASE_API_KEY }},\
_NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=${{ secrets.FIREBASE_AUTH_DOMAIN }},\
_NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=${{ secrets.FIREBASE_MESSAGING_SENDER_ID }},\
_NEXT_PUBLIC_FIREBASE_APP_ID=${{ secrets.FIREBASE_APP_ID }}

      - name: Deploy to Cloud Run
        run: |
          gcloud run deploy web \
            --image asia.gcr.io/[your_project_name] \
            --platform managed \
            --region asia-northeast1 \
            --update-secrets=/secrets/[your_key].json=firebase-admin-key:latest \
            --update-env-vars=GOOGLE_APPLICATION_CREDENTIALS=/secrets/[your_key].json,FIREBASE_PROJECT_ID=${{ secrets.GCP_PROJECT_ID }}

ポイント

  1. 事前準備

-update-secrets オプションで指定するシークレットは、あらかじめ Google Cloud Secret Manager に作成し、対象のサービスアカウントに適切なアクセス権を付与しておく必要あり
詳細は Secret Manager ドキュメント を参照

Cloud Build の設定ファイルには、必要なビルドステップや環境変数の定義を記載する
詳細は Cloud Build の基本的な設定 を参照

  1. Cloud Build でのビルド

gcloud builds submit で Cloud Build を実行し、-substitutions オプションを用いてビルド時に必要な _NEXT_PUBLIC 系環境変数を注入

  1. Cloud Run へのデプロイ

gcloud run deploy を利用し、ビルド済み Docker イメージを Cloud Run にデプロイ
-update-secrets を用いて Secret Manager のシークレットをコンテナにマウントし、-update-env-vars でランタイムの環境変数を設定

まとめ

フェーズ 設定方法 注意点
ビルド時 gcloud builds submit の --substitutions オプション ビルドに必要な環境変数を設定し、Next.js のクライアント側へ正しく値をバンドルする
デプロイ時 gcloud run deploy の --update-env-vars オプション ビルド済みアプリの実行時に必要な変数やシークレットを、コンテナ起動時に注入する

Discussion