よくある質問とトラブルシューティング

最終更新日: 2026/09/22 / EpoCanvas 公式アーキテクチャ仕様

EpoCanvas Docs の使用・執筆・デプロイ中に異常に遭遇したら、まずここで当てはまるものを探してください。問題は「ローカル起動 → ドキュメント執筆 → 検索 → デプロイ」の順に並んでいます。各問題には原因と、動作確認済みの解決方法を記載しています。

1. ローカルの起動とインストールの問題

Q1: `pnpm run dev` を実行するとポート 4321 が使用中と表示される

原因: 以前に起動した開発サーバーが完全に終了していないか、別のプログラムがポート 4321 を占有しています。
解決方法: 別のポートで起動します:
Terminal window
```
pnpm run dev -- --port 4322
```

Q2: 依存関係のインストール時に Sharp モジュールのコンパイルエラーが出る

原因: Sharp はビルド時に画像を圧縮する基盤の C++ モジュールです。Node.js のバージョンが変わると、古いキャッシュが合わなくなることがあります。
解決方法: 依存関係をクリーンアップしてから再インストールします:
Terminal window
```
rm -rf node_modules pnpm-lock.yaml
pnpm install
```

Q3: `pnpm install` を実行すると `packages field missing or empty` エラーになる

原因: pnpm-workspace.yaml の内容が空か、形式が不完全です。pnpm はこれをワークスペース設定ファイルとして解析し、エラーを出します。
解決方法: ファイルに packages フィールドが含まれていることを確認します:
```
packages:
  - .
```

2. ドキュメント執筆とレンダリングの問題

Q4: 新しい Markdown を作成したのに、左側のサイドバーに表示されない

原因: サイドバーのカタログは手動で宣言する仕組みで、新規ファイルは設定への登録が必要です。
解決方法: astro.config.mjs を開き、sidebar 配列の適切なグループに追加します:
```
{ label: '新機能の説明', link: '/canvas/new-feature/' }
```

Q5: ターミナルに `"title" is required` エラーが出る

原因: Markdown の先頭で title を書き忘れたか、先頭の 3 つのハイフン --- の形式が不正です。
解決方法: ファイル最上部の Frontmatter を確認します:
```
---
title: 記事タイトル
description: 記事の説明
---
```

Q6: 同じ内容の大きな見出しが 2 つ表示される

原因: 本文にもう 1 つレベル 1 の見出し # を書いています。Frontmatter の title はすでに大見出しとしてレンダリングされるため、本文で # を書くと必ず重複します。
解決方法: 本文から # 見出しを削除し、節は ## から始めます。完全なルールはレンダリングルールの詳細を参照してください。

Q7: `> [!TIP]` と書いたのに吹き出しが色づかず、文字がそのまま表示される

原因: GitHub 風の > [!TIP] 引用ブロック構文はサポートされておらず、Markdown コンパイラが認識しません。
解決方法: 3 コロン構文に書き換えます:
```
:::tip
こちらが正しい書き方です。
:::
```

Q8: 挿入した画像が割れたアイコンで表示される

原因: 画像のパスが間違っているか、画像が public/ 静的ディレクトリに置かれていません。
解決方法:
1. 画像が public/images/canvas/ui-docs-reading.png に保存されていることを確認します。
2. 参照するときは / で始まる絶対パスを使います: ![説明](/images/canvas/ui-docs-reading.png)。../public/... のような相対パスは書かないでください。

3. 検索機能の問題

Q9: ローカルの `pnpm dev` でデバッグしているとき、サイト全体検索で新しく書いた記事が見つからない

原因: サイト全体検索はビルド時に生成される Pagefind のインデックスに依存しています。開発モードでは Ctrl+K ダイアログがインデックスを読み込まず（開いても検索入力欄がない）、サイト全体検索は使用できません。これはフレームワークの想定動作であり、サイトの故障ではありません。
解決方法: 完全にビルドしてからプレビューサーバーで検証します:
Terminal window
```
pnpm run build
pnpm run preview
```
トップバーのページ内検索はこの制限を受けないため、開発中はそれを使って現在のページの内容を直接探せます。

Q10: `Ctrl+K` を押しても検索ポップアップが開かない

原因: 一部の IME（入力メソッド）、クリップボードツール、スクリーンショットソフトが Ctrl+K / Cmd+K のショートカットキーを占有しています。
解決方法: 検索ボックスの右側にある Ctrl K の小さなバッジをクリックしても、サイト全体検索のポップアップを開けます。

4. Cloudflare Pages のデプロイの問題

Q11: バインドしたばかりのカスタムドメインで SSL ハンドシェイク失敗 (Error 525) と表示される

原因: Cloudflare が新しいドメインに Universal SSL 証明書を発行するには、全世界に反映されるまで 2〜5 分かかります。
解決方法: 数分待ってから強制リロードします（Ctrl+F5 / Cmd+Shift+R）。それまでは <プロジェクト名>.pages.dev のデフォルトドメインでアクセスできます。これは常に利用可能です。

Q12: `pnpm run deploy` を実行すると `Project not found` エラーになる

原因: デプロイコマンドの --project-name パラメータが、Cloudflare コンソールのプロジェクト名と一致していません。または、このマシンでログインしていない可能性もあります。
解決方法:
1. まず npx wrangler whoami を実行してログイン済みか確認します。
2. Cloudflare コンソールでプロジェクト名を確認し、必要に応じて package.json の deploy スクリプトの --project-name パラメータを修正します。

5. コミット前のローカルセルフチェック

GitHub にプッシュする前に、次のコマンドで完全なセルフチェック（型チェック + 全量ビルド）を行います:

pnpm exec astro check && pnpm run build

astro check が 0 errors を出力し、ビルドが Complete! で終われば、ドキュメントに構文エラーはなく、安心してコミットできます。リポジトリの CI（build.yml）はプッシュ後に同じビルドを実行するため、ローカルで先に通しておけば CI の失敗を避けられます。