サーバーサイドレンダリングされたアプリケーションのトラブルシューティング

Amplify ホスティングコンピューティングで SSR アプリをデプロイする際に予期しない問題が発生した場合は、以下のトラブルシューティングトピックを確認してください。ここで問題の解決策が見つからない場合は、Amplify Hosting GitHub Issues リポジトリのSSR ウェブコンピュートトラブルシューティングガイドを参照してください。

フレームワークアダプターの使い方を知りたい

フレームワークアダプターを使用する SSR アプリケーションのデプロイで問題が発生する場合は、「SSR フレームワークのオープンソースアダプターの使用」を参照してください。

Edge API ルートが原因で Next.js ビルドが失敗する

現在、Amplify は Next.js エッジ API ルートをサポートしていません。Amplify でアプリをホストするときは、エッジ以外の API とミドルウェアを使用する必要があります。

オンデマンドの Incremental Static Regeneration がアプリで機能しない

バージョン 12.2.0 以降、Next.js は特定のページの Next.js キャッシュを手動で削除するインクリメンタル・スタティック・リジェネレーション (ISR) をサポートしています。ただし、Amplify は現在オンデマンド ISR をサポートしていません。アプリが Next.js のオンデマンド再検証を使用している場合、アプリを Amplify にデプロイしてもこの特徴量は機能しません。

アプリケーションのビルド出力が最大許容サイズを超えています

現在、Amplify が SSR アプリでサポートしているビルドの最大出力サイズは 220 MB です。アプリのビルド出力のサイズが最大許容サイズを超えていることを示すエラーメッセージが表示された場合は、削減する手順を実行する必要があります。

アプリのビルド出力のサイズを減らすには、アプリのビルドアーティファクトを検査し、更新または削除すべき大きな依存関係を特定します。まず、ビルドアーティファクトをローカルコンピュータにダウンロードします。次に、ディレクトリのサイズを確認します。例えば、node_modules ディレクトリには、Next.js サーバーのランタイムファイルによって参照される @swc や @esbuild などのバイナリがある場合があります。これらのバイナリは、ランタイムに必須ではないため、ビルドの 後に 削除できます。

以下の手順に従って、アプリのビルド出力をダウンロードし、 AWS Command Line Interface (CLI) を使用してディレクトリのサイズを検査します。

Next.js アプリのビルド出力をダウンロードして検査するには

1. ターミナルウィンドウを開いて、次のコマンドを実行します。アプリ ID、ブランチ名、ジョブ ID をユーザー独自の情報に変更します。ジョブ ID には、調査中の失敗したビルドのビルド番号を使用します。

   aws amplify get-job --app-id abcd1234 --branch-name main --job-id 2

2. ターミナル出力で、job、steps、stepName: "BUILD" セクションで署名付きアーティファクト URL を見つけます。URL は、次の出力例では赤で強調表示されます。

   "job": {
       "summary": {
           "jobArn": "arn:aws:amplify:us-west-2:111122223333:apps/abcd1234/main/jobs/0000000002",
           "jobId": "2",
           "commitId": "HEAD",
           "commitTime": "2024-02-08T21:54:42.398000+00:00",
           "startTime": "2024-02-08T21:54:42.674000+00:00",
           "status": "SUCCEED",
           "endTime": "2024-02-08T22:03:58.071000+00:00"
       },
       "steps": [
           {
               "stepName": "BUILD",
               "startTime": "2024-02-08T21:54:42.693000+00:00",
               "status": "SUCCEED",
               "endTime": "2024-02-08T22:03:30.897000+00:00",
               "logUrl": "https://aws-amplify-prod-us-west-2-artifacts.s3.us-west-2.amazonaws.com/abcd1234/main/0000000002/BUILD/log.txt?X-Amz-Security-Token=IQoJb3JpZ2luX2V...Example

3. URL をコピーしてブラウザウィンドウに貼り付けます。artifacts.zip ファイルはローカルコンピュータにダウンロードされます。これがユーザーのビルド出力です。

4. du ディスク使用量コマンドを実行して、ディレクトリのサイズを検査します。次のコマンド例では、compute および static のディレクトリのサイズを返します。

   du -csh compute static

   compute および static のディレクトリのサイズ情報を含む出力の例を次に示します。

    29M    compute
   3.8M    static
    33M    total

5. compute ディレクトリを開き、node_modules フォルダを見つけます。ファイルの依存関係を確認し、フォルダのサイズを小さくするために更新または削除します。

6. アプリにランタイムに必要のないバイナリがある場合は、アプリの amplify.yml ファイルのビルドセクションに次のコマンドを追加して、ビルド後にそれらを削除します。

   - rm -f node_modules/@swc/core-linux-x64-gnu/swc.linux-x64-gnu.node
   - rm -f node_modules/@swc/core-linux-x64-musl/swc.linux-x64-musl.node

   次の例は、これらのコマンドを本番用ビルドの実行の 後に 追加した amplify.yml ファイルのビルドコマンドセクションを示します。

   frontend:
     phases:
       build:
         commands:
            -npm run build
            
            // After running a production build, delete the files
            - rm -f node_modules/@swc/core-linux-x64-gnu/swc.linux-x64-gnu.node
            - rm -f node_modules/@swc/core-linux-x64-musl/swc.linux-x64-musl.node

ビルドがメモリ不足エラーで失敗します

Next.js では、ビルドアーティファクトをキャッシュして、以降のビルドのパフォーマンスを向上させることができます。さらに、Amplify の AWS CodeBuild コンテナは、ユーザーに代わってこのキャッシュを圧縮して Amazon S3 にアップロードし、後続のビルドパフォーマンスを向上させます。これにより、ビルドがメモリ不足エラーで失敗する可能性があります。

ビルドフェーズ中にアプリがメモリ制限を超えないようにするには、次のアクションを実行します。まず、ビルド設定の cache.paths セクションから.next/cache/**/*を削除します。次に、ビルド設定ファイルから環境変数NODE_OPTIONSを削除します。代わりに、Amplify コンソールで環境変数NODE_OPTIONSを設定して、ノードの最大メモリ制限を定義します。Amplify コンソールを使用した環境変数を設定する方法の詳細については、「環境変数の設定」を参照してください。

これらの変更を加えたら、ビルドをやり直してください。成功したら、ビルド設定ファイルの cache.paths セクションに.next/cache/**/*を追加し直してください。

ビルドパフォーマンスを向上させるための Next.js キャッシュ設定の詳細については、Next.js のウェブサイトの「AWS CodeBuild」を参照してください。

アプリケーションの HTTP レスポンスサイズが大きすぎる

現在、Web Compute プラットフォームを使用する Next.js 12 以降のアプリで、Amplify がサポートしている最大応答サイズは 5.72 MB です。この制限を超える応答は、コンテンツなしで504 個のエラーをクライアントに返します。

コンピューティングアプリの起動時間をローカルで測定するにはどうすればよいですか？

次の手順を使用して、Next.js 12 以降の Compute アプリのローカル初期化/起動時間を決定します。アプリのパフォーマンスをローカルと Amplify ホスティングで比較し、その結果を使用してアプリのパフォーマンスを向上させることができます。

Next.js コンピューティングアプリケーションの初期化時間をローカルで測定するには

1. アプリケーションの next.config.js ファイルを開き、standalone次のように outputオプションを に設定します。

   ** @type {import('next').NextConfig} */
   const nextConfig = {
     // Other options
     output: "standalone",
   };
   
   module.exports = nextConfig;

2. ターミナルウィンドウを開き、次のコマンドを実行してアプリを構築します。

   next build

3. 次のコマンドを実行して、.next/staticフォルダを にコピーします.next/standalone/.next/static。

   cp -r .next/static .next/standalone/.next/static

4. 次のコマンドを実行して、publicフォルダを にコピーします.next/standalone/public。

   cp -r public .next/standalone/public

5. 次のコマンドを実行して Next.js サーバーを起動します。

   node .next/standalone/server.js

6. ステップ 5 でコマンドを実行してからサーバーを起動するまでにかかる時間に注意してください。サーバーがポートでリッスンしている場合、次のメッセージが出力されます。

   Listening on port 3000

7. ステップ 6 でサーバーを起動した後、他のモジュールがロードされるまでにかかる時間に注意してください。たとえば、 のようなライブラリのロードには 10～12 秒bugsnagかかります。ロードされると、確認メッセージが表示されます[bugsnag] loaded。

8. ステップ 6 とステップ 7 の所要時間を一緒に追加します。この結果は、Compute アプリケーションのローカル初期化/起動時間です。

ビルドが非推奨の Node.js バージョンエラーで失敗する

問題: SSR アプリケーションビルドが Node.js バージョンがサポートされていませんというエラーで失敗します。

❌ NODE.JS VERSION NOT SUPPORTED
================================================================================
Your application uses Node.js v18.x.x, which is no longer supported.
AWS Amplify Console has ended support for Node.js 14, Node.js 16 and Node.js 18.

To deploy your application, please upgrade to Node.js 20 or later.

For detailed migration guidelines, visit: https://docs.aws.amazon.com/amplify/latest/userguide/troubleshooting-general.html#update-node-version
================================================================================   

原因: SSR アプリケーションは、非推奨の Node.js バージョン (14.x、16.x、または 18.x) を使用して構築されました。2025 年 9 月 15 日以降、Amplify はビルドプロセス中にこれらの非推奨バージョンを使用する SSR アプリケーションのデプロイをブロックします。

Node.js 20 以降を使用するようにビルド環境を更新します。詳細な手順については、「アプリケーションの Node.js バージョンを更新する必要がある」を参照してください。