トラブルシューティング
BlockTavern ドキュメント開発における一般的な問題を迅速に解決します。
開発問題
サーバー起動失敗
bash
npm run docs:dev解決方法：
- Node.js バージョンを確認（推奨 18+）
- 依存関係を再インストール：
rm -rf node_modules && npm install - ポート使用状況を確認：
netstat -ano | findstr :5173
ビルド失敗
bash
npm run docs:build解決方法：
- Markdown 構文エラーを確認
- すべての内部リンクの有効性を検証
- 設定ファイルの構文を確認
ページ異常
一般的な症状：コンテンツ表示エラー、スタイル異常
解決方法：
- ブラウザキャッシュをクリア（Ctrl+F5）
- Front Matter 形式を確認
- 画像パスの正確性を検証
検索機能無効
解決方法：
- プロジェクトを再ビルド
- ブラウザコンソールエラーを確認
- 検索設定を検証
デバッグ技術
開発デバッグ
ブラウザ開発者ツール（F12）：
- コンソールでエラー情報を確認
- ネットワークパネルでリソース読み込みを確認
- 要素パネルでスタイルをデバッグ
VitePress デバッグモード：
bash
# Windows
set DEBUG=vitepress:* && npm run docs:dev
# Linux/Mac
DEBUG=vitepress:* npm run docs:devビルドデバッグ：
bash
npm run docs:build -- --debug本番デバッグ
ローカルプレビュー：
bash
npm run docs:build
npm run docs:previewファイル確認：
- ビルド出力：
docs/.vitepress/dist/ - 静的リソース：
docs/.vitepress/dist/assets/ - ページファイル：HTML 構造を確認
常用ツール
- リンク確認：
markdown-link-checkを使用してリンクを検証 - 構文確認：
markdownlintを使用して形式を確認 - パフォーマンス分析：ブラウザ Lighthouse ツール
設定問題
サイドバーが表示されない
原因：ファイル構造が自動生成ルールに適合していない
解決方法：
- ディレクトリに
index.mdファイルが含まれていることを確認 - ファイル命名規則を確認（小文字+ハイフン）
- Front Matter 形式が正しいことを検証
多言語切り替え異常
解決方法：
language.js設定を確認- 各言語ディレクトリ構造の一致を確保
- パスマッピングが正しいことを検証
画像が表示されない
解決方法：
- 相対パスを使用：
./images/pic.png - ファイルが
public/ディレクトリに存在するか確認 - ファイル名の大文字小文字が一致することを検証
デプロイ問題
GitHub Pages デプロイ失敗
解決方法：
- GitHub Actions ワークフロー設定を確認
baseパス設定が正しいことを確保- リポジトリ権限とブランチ設定を検証
静的リソース 404
解決方法：
base設定がデプロイパスと一致するか確認- リソースファイルが
public/ディレクトリにあることを確保 - ビルド出力の完全性を検証
迅速診断
問題調査手順
- エラー情報を確認：コンソール/ターミナル出力
- ファイル構造を確認：規範に適合していることを確保
- 設定を検証：構文とパスの正確性
- クリーンリビルド：キャッシュを削除して再ビルド
- 動作バージョンと比較：Git 差分比較
# 貢献者
読み込み中...
# 変更履歴
読み込み中...
完全な履歴を表示
読み込み中...