表示・画像・接続の問題を切り分ける
画面が出ない、記事が出ない、画像が出ないなどを分けて確認します。データを消さずに、最初に見る場所を整理します。
目次
まず、何が動いて何が動かないかを見る
まず、トップページ、管理画面、問題のある記事をそれぞれ開き、どこまで表示できるかを確認します。サイト全体の問題か、特定のページや機能だけの問題かを分けると、調べる場所を絞れます。
最初に、問題のURL、発生時刻、ローカルか公開先か、直前に変えた内容、画面とログのエラーを記録します。秘密値、ログイン用リンク、個人情報は、共有する記録から除いてください。
ローカルURLが開かない
サイトを起動したコマンド入力画面(VS Codeのターミナル。Windowsではコマンドプロンプト)で、開発サーバーが動いているか確認します。npm run devを実行した場所に、そのサイトのpackage.jsonがあるかも見ます。
別のアプリが同じポートを使うと、起動URLの番号が変わる場合があります。覚えている4321へ固定して開かず、その回のコマンド入力画面に表示されたURLを使います。コマンド入力画面を閉じた場合は、サーバーも止まっている可能性があります。
404と500を分ける
| 表示 | 主な意味 | 最初に見る場所 |
|---|---|---|
| 404 | URLに対応するものが見つからない | ページファイル、スラッグ、公開状態 |
| 500 | サーバー処理の失敗 | 同時刻のサーバーログ |
| 503 | 今は処理できない状態 | 移行待ちなどを含むログと応答内容 |
| 401 | 認証が必要・無効 | ログインやトークン |
| 403 | 操作が許可されていない | 利用者の権限、要求ヘッダー |
番号だけで原因を断定しません。たとえば記事詳細の404は、ファイルがない場合だけでなく、指定スラッグの記事が公開されていない場合にも起こり得ます。
記事が表示されない
管理画面で次を順番に確認します。
- 閲覧しているサイトと、記事を編集したサイトが同じか。
- 記事を入れたコレクションが、テーマで読み込むコレクションと一致しているか。
- 記事が下書きではなく公開済みか。
- URLのスラッグと言語が一致しているか。
- テーマ側の取得条件で、意図せず除外していないか。
下書きのプレビューと、ログアウト状態の公開ページは分けて確認します。記事の保存をやり直す前に、制作担当者が取得処理のエラーも確認します。記事を読み込めなかったときに、エラーを表示せず「0件」と扱っていないかを調べます。
画像が表示されない
まず管理画面のメディア一覧で、そのファイル自体が開けるか確認します。開けないなら、アップロードが終わったかを確認します。制作担当者には、保存先や、R2をプログラムへ接続するMEDIAbindingの設定も調べてもらいます。
管理画面では開けるのにテーマに出ないなら、記事に画像が選択されているか、テーマで正しい画像欄を読み込んでいるかを確認します。メディアの値を必要とするImageへ、単なるURL文字列だけを渡していないかも見ます。
アップロード失敗なら、ファイルの種類と容量、保存先の制限を確認します。複数箇所で使っているメディアを、原因調査のためにいきなり削除しないでください。
予約時刻を過ぎても公開されない
CloudflareではCron TriggerとWorkerのscheduled処理の両方が必要です。手元で予約公開できた場合も、公開先の接続設定と動作を別に確認します。
npx emdash doctorでプロジェクト設定を見て、npx wrangler tailで実際の定期処理のログを確認します。Okは未処理の例外なく処理が終わった意味で、記事公開の成功数ではありません。公開ログ、管理画面の状態、ログアウトしたページを合わせて見ます。
新規・変更したCron Triggerには反映待ちがあるため、その点も公式の公開手順(別タブで開く)で確認します。
プラグインが動かない
SANDBOX_NOT_AVAILABLEが出た場合は、サンドボックス型のプラグインを動かす仕組みであるrunnerを先に調べます。CloudflareならLOADERとPluginBridge、Node.jsならworkerdの導入と起動が対象です。
実際にインストールされたworkerdの有無を調べる例です。サイトのフォルダーで、OSに合う方だけを実行します。Windowsではコマンドプロンプトを使います。
Macの場合
./node_modules/.bin/workerd --versionWindowsのコマンドプロンプトの場合
node_modules\.bin\workerd.cmd --version未導入のものを自動ダウンロードするコマンドではなく、手元にある実体を確認します。
確認用APIは動くのに保存フックだけ動かないなら、プラグインに許可する操作であるcapabilityが、必要な分だけ宣言されているかを確認します。runnerの問題を避けるためだけに、本番でsandbox: falseへ切り替えないでください。
更新後に503になった
Cloudflareでは、大きな内部移行をCLIで適用するまで503になる場合があります。今回の版が生成した移行内容の一覧(manifest)、対象DB、emdash migrate --statusの結果を確認し、更新手順へ戻ります。
データベースを消して初期設定し直すのは、復旧手段ではありません。ログイン情報や記事を失うので、既存データを残して原因を切り分けます。
調査結果を渡す形
相談するときは「公開先の特定記事だけ404。管理画面では公開済み。直前にスラッグ変更。ほかの記事は表示できる」のように、確認済みの範囲をまとめます。
変更は一つずつ行い、その前後を同じURL・同じログイン状態で比べます。直ったら、原因、修正した場所、確認した操作を残しておくと、同じ問題に戻ったときに役立ちます。