コンテンツにスキップ
varsha
このページの翻訳は LLM によって生成されています。誤りに気づいた場合は GitHub で issue を開いてお知らせください。

トラブルシューティング

このページでは、varshaを使用する際によく遭遇する問題とその解決方法を説明します。

インストールの問題

Section titled “インストールの問題”

依存関係のインストールが失敗する

Section titled “依存関係のインストールが失敗する”

症状： npm installがエラーで失敗する

解決方法：

  1. Node.jsバージョンを確認（18.17.0または20.3.0+が必要）：
    ターミナルウィンドウ
    node --version
  2. node_modulesとpackage-lock.jsonを削除して再インストール：
    ターミナルウィンドウ
    rm -rf node_modules package-lock.json
    npm install
  3. npmキャッシュをクリア：
    ターミナルウィンドウ
    npm cache clean --force

EACCES / 権限エラー

Section titled “EACCES / 権限エラー”

npmでグローバルパッケージのインストール時に権限エラーが発生する場合は、nvmやfnmなどのNodeバージョンマネージャーを使用するか、npmのプレフィックスを変更してください。

開発サーバーの問題

Section titled “開発サーバーの問題”

ポート4321が既に使用されている

Section titled “ポート4321が既に使用されている”

症状： npm run devで「Port 4321 is already in use」エラー

解決方法： 別のポートで起動：

ターミナルウィンドウ
npm run dev -- --port 3000

ホットリロードが動作しない

Section titled “ホットリロードが動作しない”

WSL2またはネットワークドライブを使用している場合、ファイル監視が動作しないことがあります：

  1. WSL2の場合：プロジェクトファイルがLinuxファイルシステム上にあることを確認
  2. またはポーリングモードを有効化：
    ターミナルウィンドウ
    CHOKIDAR_USEPOLLING=true npm run dev

ページが真っ白になる

Section titled “ページが真っ白になる”

ブラウザのコンソールでJavaScriptエラーを確認してください。よくある原因：

  • 存在しないコンポーネントをインポートしている
  • Astroコンポーネントで無効なpropsを渡している
  • CSSが読み込まれていない

ビルドエラー

Section titled “ビルドエラー”

document is not definedまたはwindow is not defined

Section titled “document is not definedまたはwindow is not defined”

Astroはデフォルトでサーバーサイドレンダリングを使用します。ブラウザAPIにアクセスするには：

<script>
  // クライアントサイドのコードは<script>タグ内に記述
  const theme = localStorage.getItem('theme');
</script>

または、ブラウザAPIを使用するコンポーネントにclient:loadディレクティブを使用：

<ThemeSwitcher client:load />

コンテンツコレクションのエラー

Section titled “コンテンツコレクションのエラー”

ブログ記事のfrontmatterに問題がある場合、ビルドエラーが発生します：

  • すべての記事にtitle、description、pubDateがあることを確認
  • pubDateが有効な日付形式（YYYY-MM-DD）であることを確認
  • draft: trueの記事は本番ビルドから除外される

ビルド後に画像が表示されない

Section titled “ビルド後に画像が表示されない”
  • src/assets/の画像はAstroコンポーネントでインポートする必要があります
  • public/の画像は/image-name.pngのようにルートからの絶対パスで参照
  • 大文字と小文字が一致していることを確認（デプロイ後に問題になることがあります）

デプロイの問題

Section titled “デプロイの問題”

Vercelデプロイが失敗する

Section titled “Vercelデプロイが失敗する”
  1. ビルドログで具体的なエラーを確認
  2. Node.jsバージョンがVercelのプロジェクト設定で正しく設定されていることを確認
  3. ビルドコマンドがnpm run buildで、出力ディレクトリがdistであることを確認

Netlifyビルドが失敗する

Section titled “Netlifyビルドが失敗する”

ビルドコマンドがnpm run build、公開ディレクトリがdistに設定されていることを確認してください。

Cloudflare Pagesビルドがタイムアウトする

Section titled “Cloudflare Pagesビルドがタイムアウトする”
  1. ビルドコマンドがnpm run buildであることを確認
  2. ビルド出力ディレクトリがdistであることを確認
  3. 必要に応じて環境変数を追加

デプロイ後に404エラーが発生

Section titled “デプロイ後に404エラーが発生”
  • カスタムドメインのDNS伝播を待つ（最長48時間）
  • ホスティングプラットフォームのリダイレクト/リライトルールを確認
  • Astroのbuild.format設定がデフォルト（directory）であることを確認

スタイリングの問題

Section titled “スタイリングの問題”

テーマが適用されない

Section titled “テーマが適用されない”
  • data-theme属性が<html>要素に設定されていることを確認
  • テーマのCSSがグローバルCSSファイルに含まれていることを確認
  • ブラウザのDevToolsでgetComputedStyle(document.documentElement).getPropertyValue('--color-bg')をチェック

CSSカスタムプロパティが未定義

Section titled “CSSカスタムプロパティが未定義”

トークンを使用する前に:rootまたは[data-theme]セレクタで定義されていることを確認してください。

助けを求める

Section titled “助けを求める”

それでも問題が解決しない場合：

GitHub Issues

バグ報告や機能リクエストはGitHubに投稿してください。

Issueを作成 →

Built with varshamyndlabs