Next.js × DockerでGoogle認証を導入する時の「環境変数」ベストプラクティス

Next.jsでGoogle認証（OAuth）を導入し、Dockerで本番運用するときにハマるポイントです。

環境変数の渡し方が問題だった場合の対策をお伝えします。

Next.js × DockerでGoogle認証を導入する時の「環境変数」ベストプラクティス

Next.jsの環境変数の基本

Next.jsの環境変数には2種類あります。

❗️NEXT_PUBLIC_ 付きの環境変数は 「ビルド時」 に読み込まれ、JSに静的に埋め込まれます。

ビルド時にNEXT_PUBLIC_GOOGLE_CLIENT_IDが空だと、アプリ中のclient_idは空のままになります。実行時に渡しても意味がありません。

Docker運用での落とし穴

よくある間違った設定は、以下の通り。

# ❌ これはビルド時には使えない
services:
  frontend:
    environment:
      - NEXT_PUBLIC_GOOGLE_CLIENT_ID=xxxxxx.apps.googleusercontent.com

Dockerでは、environment で渡しても 実行時 にしか使えません。

そのため、クライアントサイド用の環境変数には反映されずビルド時に反映されないのです。

正しい設定方法（build.args を使う）

結論、build.argsを使ってビルド時に環境変数を渡します。

services:
  frontend:
    build:
      context: ./frontend
      args:
        NEXT_PUBLIC_API_URL: https://api.example.com/api
        NEXT_PUBLIC_GOOGLE_CLIENT_ID: xxxxxxxx.apps.googleusercontent.com

上記のようにdocker-compose.yamlを書いた場合には、Dockerfileに以下のようにします。

# クライアント用の環境変数をビルド時に受け取る
ARG NEXT_PUBLIC_API_URL
ENV NEXT_PUBLIC_API_URL=${NEXT_PUBLIC_API_URL}

ARG NEXT_PUBLIC_GOOGLE_CLIENT_ID
ENV NEXT_PUBLIC_GOOGLE_CLIENT_ID=${NEXT_PUBLIC_GOOGLE_CLIENT_ID}

これで Next.js のビルド時に NEXT_PUBLIC_GOOGLE_CLIENT_ID が正しく埋め込まれます！

最後にコンテナの再ビルド・再起動をする

環境変数を修正したら、必ず再ビルドしてください。

docker-compose down
docker-compose build --no-cache
docker-compose up -d

値が空のままビルドされると、再起動しても直りません。
再ビルドが必須です！

よくある質問（FAQ）

Q. environment は設定不要？

NEXT_PUBLIC_ 環境変数は、基本的にbuild.argsのみで大丈夫です。

一方で、APIやSSRなどのサーバーサイドで参照する変数の場合にはenvironmentへの登録が必要です。

Q. .env.local は本番で使える？

Docker本番では反映されないので、使えません。

.env.localはその名の通り、ローカル開発用の環境変数設定ファイルです。

まとめ

本記事の結論をまとめます。

Next.js × Docker で Google OAuth を使うときは、以下を気をつけましょう。

これはGoogle認証だけでなく、すべての NEXT_PUBLIC_ 環境変数に共通です。