JSS Next.jsアプリのトラブルシューティング
このページの翻訳はAIによって自動的に行われました。可能な限り正確な翻訳を心掛けていますが、原文と異なる表現や解釈が含まれる場合があります。正確で公式な情報については、必ず英語の原文をご参照ください。
JSSアプリケーションのデバッグを助けるために、JSSが提供するデバッグログユーティリティの使用をお勧めします。
ほとんどのエラーを防ぐには、以下の方法を取ることができます:
-
アプリで使用されるすべての環境変数に値があるか確認してください。サンプルアプリは以下の順序で環境変数を検索します:
- scjssconfig.json.
- .env.
- .env.local (局所環境のみ)
-
複数のファイルに同じ変数の定義が含まれている場合、アプリケーションは最後に見つけた値を使用します。
変数名や記述についてはサンプル .envファイルをご参照ください。
-
APIキーの設定が正しくできているか確認してください。
-
プロジェクトのサイト定義とアプリの定義がSitecoreの設定で正しいか確認してください。必要なプロパティのリストについてはSitecoreアプリの設定 を参照してください。
-
編集シークレットJSS設定しているか確認してください。Next.jsアプリで使うJSS_EDITING_SECRET値は、Sitecoreインスタンスで使われているものと一致しなければなりません。
-
GraphQLエンドポイントがpackage.jsonとSitecoreアプリの設定で正しいか確認してください。ブラウザでGraphQL IDEを開き、設定(<sitecore hostname + graphQL endpoint>/ui?sc_apikey=
)の値を使ってエンドポイントが正常に動作しているか確認してください。
サーバーサイドのJavaScriptエラー
npm installまたはbuildステップ中に予期せぬJavaScriptエラー、特に他のチームメンバーが再現できないエラーに遭遇した場合は、使用されているNodeとnpmのバージョンを確認してください。ターミナルから実行してください:
node -v npm -v
私たちはJSSを長期 サポート(LTS)バージョンのNodeでテストしています。これらは通常、最新の公式Nodeバージョンより1つ大きな遅れです。
CI/本番環境で使用されるNode/npmのバージョンは、ローカル環境で使われているバージョンと異なる場合があります。プロジェクト構成がpackage.jsonで特定のNode/npmバージョンを必要としない場合、デプロイメントエージェントは通常、利用可能な最新のバージョンか環境固有のデフォルトバージョンを使って構築します。
テストのためにローカル環境で複数のNodeバージョンを切り替える必要がある場合は、nやnvmのようなサードパーティ製パッケージを使うことができます。
SSL証明書に関するエラー
プライベート署名証明書を使ってローカルのSitecoreインスタンスを扱っている場合、以下のエラーが発生する可能性があります。
Error: unable to verify the first certificate Error: UNABLE TO VERIFY LEAF SIGNATURE UnauthorizedError: invalid signature
このエラーを解決するには、Node.js用のSitecore CA証明書を設定してください。
JSSアプリをローカルにデプロイする際のエラー
インポートロールに正しい権限がない場合、以下のエラーが発生する可能性があります:
IMPORT ERROR(S) OCCURRED! Exception thrown while importing JSS app Exception: Sitecore.Exceptions.AccessDeniedException Message: AddFromTemplate - Add access required
解決策については「 AzureでJSSアプリケーションをインポートする際のエラー 」を参照してください。
データ取得の問題
JSS Next.jsアプリの構築とレンダリングは、GraphQLを使ってデータを取得することにかかっています。ビルド失敗やページをレンダリングできないアプリの最も一般的な原因は、データ取得プロセスの問題です。
<sitecore hostname + graphQL endpoint>/ui?sc_apikey=
静的生成機能をサポートするために、Next.js JSSアプリはGraphQLクエリを使ってSitecoreパスを取得します。GraphQL IDEで以下のクエリを実行してみてください:
# YOUR_PATH should be the ID of your site root (home page) in lower-case, with dashes removed.
YOUR_LANGUAGE should be your default language, as defined in package.json
このページの翻訳はAIによって自動的に行われました。可能な限り正確な翻訳を心掛けていますが、原文と異なる表現や解釈が含まれる場合があります。正確で公式な情報については、必ず英語の原文をご参照ください。
query{ search(where: { AND: { name:"_path", value:"YOUR_PATH" }, { name:"_language", value:"YOUR_LANGUAGE" }, { name:"_hasLayout", value :"true" }
}) { total results { url { path } } }" }
期待された結果が見られない場合は、以下のステップを試してください。
- Sitecoreコントロールパネルで「Populate Solr Managed schema」を使ってSolrスキーマを入力してください。
- Sitecoreコントロールパネルでインデックスマネージャーを使ってインデックスを再構築してください。
- 検索対象の言語に合ったバージョンがあるかどうか、コンテンツが用意されているか確認してください。
Sitecoreでアイテムを編集しようとしたときのエラー
Sitecore Editor Roleで新しいユーザーを作成した後、SitecoreでJSSアプリの項目を編集しようとすると、そのユーザーに読み取り権限がないと警告されることがあります。
回避策として、System/Workflows/JSS開発ワークフロー項目のWorkflow State Writeを手動で設定し、最終的な「公開済み」状態を編集可能にします。これにより、ユーザーは「ロック&編集」オプションを使って新しいバージョンのアイテムを作成できます。
エクスペリエンスエディターでのホストタイムアウトのレンダリング問題
Experience Editorを使ってHTTPレンダリングエンジン(Next.jsアプリなど)を使用するよう設定したJSSアプリを初めて開くと、レンダリングホストからタイムアウトエラーが表示され、メッセージThe operation has timed out。ログには以下の内容が確認できます:
10292 `10
` ERROR JSS Error occurred during POST to remote rendering host: `http://localhost:3000/api/editing/render\` 10292 `10` ERROR The operation has timed out Exception: System.Net.WebException Message: The operation has timed out Source: System at System.Net.WebClient.UploadDataInternal(Uri address, String method, Byte data, WebRequest& request) at System.Net.WebClient.UploadString(Uri address, String method, String data) at Sitecore.JavaScriptServices.ViewEngine.Http.RenderEngine.InvokeT(String moduleName, String functionName, Object functionArgs)問題を解決するには、\App_Config\Sitecore\JavaScriptServices\Sitecore.JavaScriptServices.ViewEngine.Http.configファイルを編集してRequestTimeoutMs設定の値を上げてください。例えば:
ペイロードサイズのためレンダリングホストへの接続が失敗しました
ペイロードをExperience Edgeに送信した際に (413) Payload Too Largeエラーが発生した場合は、サンプルNext.jsアプリでデフォルトで2MBに設定されているsizeLimitプロパティを増幅することをお勧めします。
この変更は以下のファイルで行う必要があります:
- \src\pages\api\editing\render.ts
- \src\pages\api\editing\key.ts
以下の例は、ペイロードサイズ制限を5MBに増やした後のrender.tsの関連部分を表しています。
... export const config = { api: { bodyParser: { sizeLimit: "5mb", }, responseLimit: false, }, }; ...
GraphQLクエリエラーは、SXAを搭載したSitecoreインスタンスを使ってNext.jsアプリを起動しようとします
JSSテナントとSXA連携を持ち、Next.jsアイテムをJSSテナントにデプロイする場合、Next.jsアプリを本番モードで起動しようとした際にGraphQLクエリエラーが発生することがあります。
Error: Valid value for rootItemId not provided and failed to auto-resolve app root item.
このエラーは、Next.jsアプリとNext.js JSSテナントにデプロイされたアプリアイテムが異なるテンプレートを参照しているため、クエリが失敗するため発生します。
エラーを防ぐために、GraphQLサービスのインスタンスに対するrootItemIdを次のように定義してください。
- /src/lib/sitemap-fetcher/plugins/graphql-sitemap-service.ts.
- /src/lib/dictionary-service-factory.ts.
GraphQL内省データ生成時の誤差
GraphQLスキーマが変更された場合、GraphQLの内省データを再生成しなければなりません。
サンプルアプリでは、jss graphql
。!注このコマンドで内部的に呼び出すスクリプトは、scjssconfig.jsonファイルが入力されている必要があります。ファイルを生成するには、JSSアプリをSitecoreに接続する必要があります。
VercelはローカルのSitecore環境からのデータを表示できません
ngrokを使ってローカルSitecoreエンドポイントをVercelに公開する場合は、host-headerフラグを使用していることを確認してください。例えば、
ngrok http -host-header=rewrite
Sitecoreのイメージはlocalhostで読み込まれません
localhostドメインを使ってアプリケーションにSitecore画像が読み込まれない場合は、Next.jsプロキシ経由で画像をリクエストしようとしているため、エラー500 - Invalid URI: The hostname could not be parsed。
localhostドメインにSitecore画像を読み込むには、内容リゾルバのIncludeServerUrlInMediaUrls属性をtrueに設定し、画像URLにSitecore URLを含める必要があります。例えば:
この設定が適用されると、アプリケーションは直接Sitecoreから画像を要求します。
!重要本番環境では、IncludeServerUrlInMediaUrls属性の値をfalseに変更しなければなりません。
Experience Editorの統合がプロトコルの不一致エラーにより壊れます
Vercel以外のプラットフォームでNext.jsアプリケーションをホストする場合、Experience Editorとの連携がプロトコルの不一致エラーで動作しなくなった場合は、EditingRenderMiddlewareを使ってデフォルトプロトコルをオーバーライドしてください。
Experience Editorでのデータキャッシュミスおよび断続的な500エラーの編集
Vercel以外のプラットフォームでNext.jsアプリケーションをホストする場合、Node.js環境でキャッシュミスエラーが発生することがあります。例えば:
2022-10-12 `16
`:42: Error: Unable to get editing data for preview {"key":"0518d8c6-b7ca-4c73-86c2-a29d971ebeab-2xqnbg0jpx","serverUrl":"https://your-url.com"} at SitecorePagePropsFactory.createPreviewModePage (/opt/web/.next/server/chunks/9694.js:1190) at runMicrotasks (この問題はContent Managementインスタンスで500エラーを引き起こします。例えば:
3112 `16
` ERROR The remote server returned an error: (500) Internal Server Error. Exception: System.Net.WebException Message: The remote server returned an error: (500) Internal Server Error. Source: System at System.Net.WebClient.UploadDataInternal(Uri address, String method, Byte data, WebRequest& request) at System.Net.WebClient.UploadString(Uri address, String method, String data) at Sitecore.JavaScriptServices.ViewEngine.Http.RenderEngine.InvokeT(String moduleName, String functionName, Object functionArgs)このようなエラーは、編集データキャッシュが使用する一時ディレクトリの不安定性によって引き起こされます。エラーを解決するには、ディスクベースの編集キャッシュ実装で使われているデフォルトのディレクトリを上書きしてください。