コンテンツにスキップ

トラブルシューティング

Astroは、コードのトラブルシューティングとデバッグを支援するため、いくつかのツールを提供しています。

ターミナルで表示される一般的なエラーメッセージとその意味、および対処法を紹介します。

Cannot use import statement outside a module (モジュール外でimport文が使えません)

セクションタイトル: Cannot use import statement outside a module (モジュール外でimport文が使えません)

Astroコンポーネントでは、<script>タグはデフォルトでJavaScriptモジュールとして巻き上げられロードされます。タグにis:inlineディレクティブ (EN)などの属性が含まれていると、このデフォルトの動作は解除されます。

解決方法: もし、<script>タグに何らかの属性を追加している場合は、import文を使用できるようにtype="module"属性も追加する必要があります。

ステータス: 期待されるAstroの動作、意図したとおりです。

自分だけの問題ではないと思うなら?
この問題を報告した人が他にいないか確認してください!

Unable to render component(コンポーネントをレンダリングできません)

セクションタイトル: Unable to render component(コンポーネントをレンダリングできません)

Astroテンプレートにインポートして使用しているコンポーネントにエラーがあることを示します。

レンダリング時、windowまたはdocumentオブジェクトにアクセスしようとした場合、発生する可能性があります。デフォルトでは、Astroはコンポーネントをアイソモーフィックにレンダリングします。つまり、ブラウザのランタイムが利用できないサーバー上で実行されるということです。この事前レンダリングステップを無効にするには、client:onlyディレクティブ (EN)を使用します。

解決方法: レンダリング後にそれらのオブジェクトにアクセスしてみてください(例: ReactのuseEffect()またはVueのonMounted()とSvelteのonMount())。

ステータス: 期待されるAstroの動作、意図したとおりです。

解決方法: AstroコンポーネントまたはUIフレームワークコンポーネントの適切なドキュメントをチェックする。Astro.newからAstroのスターターテンプレートを開き、最小限のAstroプロジェクトでコンポーネントのみのトラブルシューティングを検討してください。

自分だけの問題ではないと思うなら?
この問題を報告した人が他にいないか確認してください!

Expected a default export(デフォルトのエクスポートを予想)

セクションタイトル: Expected a default export(デフォルトのエクスポートを予想)

このエラーは、無効なコンポーネントをインポートまたはレンダリングしようとしたとき、または正しく動作していないコンポーネントをインポートまたはレンダリングしようとしたときに表示されることがあります。(この特定のメッセージは、AstroでのUIコンポーネントのインポートが動作する方法によって発生します。)

解決方法: インポートおよびレンダリングしているコンポーネントのエラーを探し、それが正しく動作していることを確認してください。astro.newからAstroスターターテンプレートを開き、最小限のAstroプロジェクトであなたのコンポーネントだけをトラブルシューティングすることを検討してみてください。

ステータス: 期待されるAstroの動作、意図したとおりです。

まず、.astroコンポーネントスクリプトまたは.mdxファイルコンポーネントがインポートしているかどうか確認します。

それから、import文を確認してください。

  • インポートのリンク先が違っていませんか?(importパスを確認してください)
  • インポートしたコンポーネントと同じ名前になっていますか?(コンポーネント名と、.Astro構文にしたがっていることを確認してください。)
  • インポート時に拡張子が含まれていますか?(インポートしたファイルに拡張子が含まれているか確認してください。例: .Astro.md.vue.svelte。 注: .js(x).ts(x)のファイルのみ、拡張子は必要ありません。)

もし、コンポーネントがレンダリングされているのに(上記参照)、ユーザーの操作に反応しない場合、コンポーネントをハイドレートするためのclient:* ディレクティブ (EN)が不足している可能性があります。

デフォルトでは、UIフレームワークコンポーネントはクライアントでハイドレーションされません。もしclient:*ディレクティブが提供されない場合、そのHTMLはJavaScriptなしでページにレンダリングされます。

Astroの起動時に "Cannot find package 'react'"(または同様の)警告が表示された場合、そのパッケージをプロジェクトにインストールする必要があることを意味します。すべてのパッケージマネージャーが、peer dependenciesを自動的にインストールするわけではありません。Node v16+でnpmを使用している場合、このセクションを気にする必要はありません。

たとえば、Reactは@astrojs/reactインテグレーションのpeer dependenciesです。つまり、公式のreactreact-domパッケージを、インテグレーションと一緒にインストールする必要があります。そうすると、インテグレーションは自動的にこれらのパッケージから取得します。

Terminal window
# 例: インテグレーションとフレームワークを一緒にインストールする
npm install @astrojs/react react react-dom

フレームワークのレンダラーやCSSツールなどのパッケージをAstroに追加する方法は、Astroのインテグレーションガイドを参照してください。

Astro.glob() - no matches found(一致するものはありません)

セクションタイトル: Astro.glob() - no matches found(一致するものはありません)

Astro.glob()を使用してファイルをインポートする場合は、必要なファイルすべてにマッチする正しいglob構文を使用するようにしてください。

たとえば、src/pages/index.Astro../components/**/*.js を使用すると、次の両方のファイルをインポートできます。

  • src/components/MyComponent.js
  • src/components/includes/MyOtherComponent.js

Astro.glob()は動的変数と文字列補間をサポートしていません。

これはAstroのバグではありません。Viteのimport.meta.glob()関数の制限によるもので、静的な文字列リテラルしかサポートしていません。

これを回避するには、代わりにAstro.glob()を使って必要なファイルをすべて含む、より大きなファイル群をインポートし、フィルタリングしてください。

src/components/featured.astro
---
const { postSlug } = Astro.props;
const pathToMyFeaturedPost = `src/pages/blog/${postSlug}.md`;
const posts = await Astro.glob('../pages/blog/*.md');
const myFeaturedPost = posts.find(post => post.file.includes(pathToMyFeaturedPost));
---
<p>
お気に入りの投稿をみてください! <a href={myFeaturedPost.url}>{myFeaturedPost.frontmatter.title}</a>
</p>

Yarn 2+、通称Berryは、Nodeモジュールの保存と管理にPlug’n’Play (PnP)という技術を使用しているため、create-astroによる新しいAstroプロジェクトの初期化やAstroでの作業中に問題を引き起こすことがあります。回避するには、yarnrc.ymlnodeLinkerプロパティnode-modulesに設定します。

nodeLinker: "node-modules"

console.log()は、Astroのコードをデバッグするためのシンプルでありながら人気のある方法です。console.logステートメントをどこに書くかによって、デバッグ出力がどこに出力されるかが決まります。

AstroのFrontmatterのconsole.log()は、常にAstro CLIを実行しているターミナルに出力されます。これは、Astroがサーバー上で動作していて、ブラウザ上では動作しないためです。

---
const sum = (a, b) => a + b;
// 例: CLIターミナルに "4 "を出力する。
console.log(sum(2, 2));
---

Astroの<script>タグ内に記述またはインポートされたコードは、ブラウザ上で実行されます。console.log()ステートメントやその他のデバッグ出力は、ブラウザのコンソールに出力されます。

フレームワークコンポーネント(ReactやSvelteなど)はユニークです。これらはデフォルトでサーバーサイドにレンダリングされ、console.log()のデバッグ出力がターミナルに表示されることを意味します。しかし、これらはブラウザ用にハイドレートすることもでき、それによってデバッグログがブラウザにも表示されるかもしれません。

これはSSR出力とブラウザのハイドレートされたコンポーネントとの間の差異をデバッグするのに便利でしょう。

Astroコンポーネントのデバッグを支援するために、Astroは組み込みの<Debug /> (EN)コンポーネントを提供し、任意の値をコンポーネントHTMLテンプレートに直接レンダリングします。これは、ターミナルとブラウザの間を行ったり来たりすることなく、ブラウザ上で素早くデバッグするのに便利です。

---
import { Debug } from 'astro/components';
const sum = (a, b) => a + b;
---
<!-- 例: {answer: 6}をブラウザに出力 -->
<Debug answer={sum(2, 4)} />

Debugコンポーネントは、さらに柔軟で簡潔なデバッグを行うためのさまざまな構文オプションをサポートしています。

---
import { Debug } from 'astro/components';
const sum = (a, b) => a + b;
const answer = sum(2, 4);
---
<!-- 例: 3つの例はすべて等価である。 -->
<Debug answer={sum(2, 4)} />
<Debug {{answer: sum(2, 4)}} />
<Debug {answer} />

Discord#supportチャンネルで、問題を説明してください。私たちはいつでも喜んでお手伝いします!

現在のアストロの未解決問題にアクセスして、既知の問題に遭遇しているかどうかを確認したり、バグレポートを提出したりできます。

また、RFCディスカッションでは、Astroの既知の制限事項があるか確認し、あなたのユースケースに関連する提案があるか確認できます。