Gatsby v4/v5 アップグレード時に 'gatsby new' がエラーで失敗します。

原因の多くは Node.jsのバージョン不足です。v4ならNode 14.15以上、v5ならNode 18以上が必須です。インストール前に node -v でバージョンを確認し、公式の Minimal Node.js version を満たしているかチェックしてください。npmのバージョンも8以上が推奨されます。

macOSで Node.js のバージョンを切り替えても反映されない場合は？

nodebrewなどでインストールしても反映されない場合、パス（PATH）の設定が古い可能性があります。.zshrc や .bash_profile に正しくシンボリックリンクが設定されているか確認しましょう。詳細は macのnode環境を作り直すセクションで解説しています。

Gatsbyのビルドエラーが解決しない時、まず試すべきことは？

依存関係のキャッシュが原因でエラーが起きることがあります。gatsby clean コマンドを実行して .cache と public フォルダを削除し、さらに npm cache clean --force でnpm側のキャッシュもクリアしてみてください。本記事のキャッシュクリアの手順が参考になります。

NetlifyでGatsby v4以降をデプロイする際の注意点は？

Netlifyの管理画面（Environment variables）で、NODE_VERSION をローカル環境と同じバージョン（例: 18）に指定する必要があります。これを忘れるとビルド時にバージョンエラーが発生します。デプロイの基本手順は Netlifyへのデプロイをご覧ください。

Gatsby アップグレード時にハマりました

Q: Gatsby v4/v5 アップグレード時に 'gatsby new' がエラーで失敗します。

原因の多くは Node.jsのバージョン不足 です。v4ならNode 14.15以上、v5ならNode 18以上が必須です。インストール前に node -v でバージョンを確認し、公式の Minimal Node.js version を満たしているかチェックしてください。npmのバージョンも8以上が推奨されます。

FAQ

Gatsby v4/v5 アップグレード時に 'gatsby new' がエラーで失敗します。: 原因の多くは Node.jsのバージョン不足 です。v4ならNode 14.15以上、v5ならNode 18以上が必須です。インストール前に node -v でバージョンを確認し、公式の Minimal Node.js version を満たしているかチェックしてください。npmのバージョンも8以上が推奨されます。

macOSで Node.js のバージョンを切り替えても反映されない場合は？: nodebrewなどでインストールしても反映されない場合、パス（PATH）の設定が古い可能性があります。.zshrc や .bash_profile に正しくシンボリックリンクが設定されているか確認しましょう。詳細は macのnode環境を作り直すセクションで解説しています。

Gatsbyのビルドエラーが解決しない時、まず試すべきことは？: 依存関係のキャッシュが原因でエラーが起きることがあります。gatsby clean コマンドを実行して .cache と public フォルダを削除し、さらに npm cache clean --force でnpm側のキャッシュもクリアしてみてください。本記事のキャッシュクリアの手順が参考になります。

NetlifyでGatsby v4以降をデプロイする際の注意点は？: Netlifyの管理画面（Environment variables）で、NODE_VERSION をローカル環境と同じバージョン（例: 18）に指定する必要があります。これを忘れるとビルド時にバージョンエラーが発生します。デプロイの基本手順は Netlifyへのデプロイをご覧ください。