Next.js × Amplify で踏んだ落とし穴3つ

Next.js を Amplify Hosting に載せる構成でつまずくのは、たいていフレームワークの側ではありません。ホスティング側の前提を知らないまま「動くはず」で進めたときです。

この記事でわかること: Next.js を AWS Amplify Hosting で動かす際に実際に踏んだ3つの落とし穴と、その対処です。①環境変数が実行時に undefined になった話 ②マージ済みなのにデプロイされていなかった話 ③見た目確認を HTTP 200 だけで終えて崩れを見逃した話——知らずに踏むと原因究明に半日以上かかる種類のものです。

• ① サーバー側の環境変数が実行時に undefined になり、原因究明に半日溶けた
• ② 連続マージでデプロイが打ち消され、マージ済みなのに本番未反映になった
• ③ HTTP 200 だけ確認し、スタイルが反映されていない崩れを見逃した

いま読んでいるこのサイトは Next.js で作り、AWS Amplify Hosting で動かしています。MVP を早く出すという意味ではよくできた組み合わせで、実際に助かっています。ただ、途中で「なぜか本番だけ壊れる」に何度かぶつかりました。どれも、あとから見れば公式ドキュメントに書いてあることでした。同じ構成を選ぶ人向けに、以下に残しておきます。

🧱なぜこの組み合わせを選んだか

「速く出す」と「あとで広げられる」を両方取りたかったからです。

MVP でいちばん避けたいのは、動かすための仕組み作りに時間を使ってしまうことです。Amplify Hosting は Next.js のサーバー側レンダリングをそのまま受けてくれるので、コンテナやサーバーの面倒を見ずに済みます。

それでいて中身は AWS なので、あとから他のサービスと組み合わせる余地が残ります。私たちの場合、フォームの受信やメール送信を同じクラウドの中で足していけたのが結果的に効きました。作り直しではなく、足し算で進められる。

💥落とし穴①: サーバー側の環境変数が undefined になる

ホスティングの管理画面に登録しただけでは、実行時には届かないことがあります。

これがいちばん時間を取られました。新しい環境変数を追加して、ホスティング側の設定に登録して、デプロイして——それでもサーバー側の処理で値が読めず、画面がエラーになる。設定は確かに入っているのに、です。

原因は Amplify Hosting の SSR 実行環境の仕様でした。私たちの構成では、Amplify のホスティング画面に登録するだけでは変数が SSR ランタイムに自動では渡らず、next.config.ts の env キーに明示した変数だけが実行時に読めるようになっていました。この env キーはビルド時にクライアントへ値を埋め込む仕組みとしても使われるため、「クライアント用の設定」だと思い込み、サーバー側の実行時参照にも同じ列挙が要ることに気づいていませんでした。

対策はシンプルで、環境変数を1つ増やすときは next.config.ts の env への追記も同じ変更に含める、をルールにしました。片方だけ足せないようにする。運用でカバーするのではなく、忘れられない形にするのが大事だと思っています。

🚦落とし穴②: マージしたのにデプロイされていない

「マージ済み」は「本番に出ている」と同じ意味ではありません。

私たちは、リポジトリの更新で自動ビルドが走る設定を使わず、CI の中から明示的にデプロイを起動する形にしています。誰が・いつ・何を出したかを一本の流れで見たかったからです。

ところがこの構成には落とし穴があります。変更を続けて2つマージすると、先に走っていたデプロイが後の実行に打ち消されることがある。そして後の変更にアプリ側の中身が含まれていないと、どちらの変更も本番に出ないまま「両方マージ済み」になります。実際にこれで、直したはずの不具合がしばらく残っていました。

いまは「マージした」で終わりにせず、デプロイが実際に走ったかを確認するところまでを1セットにしています。出ていなければ手で起動して、本番の画面を見て確認する。ドキュメントは計画、動いているものだけが現実——この構成を選ぶなら、ここは避けられない手間として見込んでおくのが安全です。

🔍落とし穴③: 確認をブラウザの見た目で終える

HTML が返ってきていても、見た目が崩れていることはあります。

デザインを変えたあとの確認を「ページが200で返ってくる」で済ませて、後から崩れに気づいたことがあります。指定したクラス名が HTML に入っていても、それに対応するスタイルが実際のビルド結果に含まれていなければ、当然そこは効きません。

それ以降、見た目に関わる変更は段を分けて確認するようにしました。ページが返るか、スタイルの定義がビルド結果に入っているか、そして実際の画面を画像で見て崩れていないか。手元の開発サーバーで確認できたことは、本番で確認できたことにはならない。ここも同じ話です。

🧭同じ構成を選ぶ人へ

整理します。①Amplify Hosting で実行時に読む環境変数は next.config.ts の env にも列挙する ②マージとデプロイは別物として扱い、出たことを確認する ③見た目の確認は実物の画面まで見る。この3つを最初から知っていれば、私たちが溶かした時間は要りませんでした。

Next.js と Amplify の組み合わせ自体は、MVP を早く出したい場面では今も勧められると思っています。落とし穴はどれも「ホスティング側の前提を知らなかった」ことに集約されていて、フレームワークの限界ではありませんでした。

もしこれから同じ構成で作るなら——最初のデプロイが通った日に、環境変数を1つ増やす練習を1回だけしてみてください。そこで詰まるかどうかで、本番運用の見通しがだいぶ変わります。

📚参考・出典

本文の落とし穴は、このサイトの運用で私たちが実際に踏んだものです。仕様そのものは以下の一次資料に書かれています。

• AWS: Deploying server-side rendered applications with Amplify Hosting（サーバー側レンダリングの対応範囲）
• AWS: Using environment variables in an Amplify application（環境変数の扱いとサーバー側での参照）
• Next.js: next.config.js の env（設定ファイル側で環境変数を列挙する仕組み）
• AWS: Amplify Hosting のビルド設定（リポジトリ更新時の自動ビルドの有効/無効）