create-react-app プロジェクトをカスタム PUBLIC_URL でビルドできない問題：詳細解説と解決策

Create React App で構築したプロジェクトを、カスタム PUBLIC_URL 環境変数を指定してビルドしようとすると、エラーが発生することがあります。これは、PUBLIC_URL の扱いに関するバグまたは仕様上の制限が原因である可能性があります。

影響

この問題は、以下の状況で発生します。

• アプリケーションをサブディレクトリにデプロイしたい場合
• アプリケーションの URL パスにプレフィックスを追加したい場合
• 静的アセットのホスティング場所を変更したい場合

原因

この問題には、主に以下の 2 つの原因が考えられます。

開発モードでの PUBLIC_URL の扱い

Create React App では、開発モード (process.env.NODE_ENV === 'development') では、PUBLIC_URL 環境変数の値が自動的に修正されます。具体的には、ホスト URL が削除され、パスのみが残されます。この動作は、開発サーバーがルートパスでアプリケーションをロードするために行われます。

PUBLIC_URL の優先順位

Create React App のビルドプロセスでは、以下の順序で PUBLIC_URL の値が参照されます。

1. package.json ファイルの homepage フィールド
2. process.env.PUBLIC_URL 環境変数
3. デフォルト値 ('/')

この順序により、package.json ファイルまたは環境変数で指定された値が優先されます。

解決策

この問題を解決するには、以下の方法を試してください。

環境変数を使用する

最も簡単な解決策は、process.env.PUBLIC_URL 環境変数を使用してカスタム URL を設定することです。以下のコマンドを実行して、ビルド前に環境変数を設定できます。

export PUBLIC_URL=/your/custom/url

homepage フィールドを使用する

package.json ファイルの homepage フィールドにカスタム URL を設定することもできます。

{
  "name": "my-app",
  "version": "1.0.0",
  "homepage": "/my/custom/url"
}

eject を使用する

Create React App の eject コマンドを使用して、プロジェクトを手動で構成することもできます。 eject を使用すると、webpack 設定ファイルに直接アクセスして、PUBLIC_URL プロパティをカスタマイズできます。

// package.json
{
  "name": "my-app",
  "version": "1.0.0",
  "scripts": {
    "start": "react-scripts start",
    "build": "export PUBLIC_URL=/my/custom/url && react-scripts build"
  }
}

この例では、package.json ファイルの scripts フィールドにカスタムビルドスクリプトを追加しています。このスクリプトは、PUBLIC_URL 環境変数を /my/custom/url に設定してから、react-scripts build コマンドを実行します。

// package.json
{
  "name": "my-app",
  "version": "1.0.0",
  "homepage": "/my/custom/url"
}

この例では、package.json ファイルの homepage フィールドにカスタム URL を設定しています。Create React App は、ビルドプロセスでこの値を PUBLIC_URL 環境変数に自動的に設定します。

1. create-react-app プロジェクトを eject コマンドを使用して手動で構成します。

npx create-react-app my-app
cd my-app
npm run eject

1. webpack.config.js ファイルを開き、output プロパティの publicPath オプションを次のように設定します。

output: {
  publicPath: '/my/custom/url'
}

1. プロジェクトをビルドします。

npm run build

注意事項

• 上記のコード例はあくまでも例であり、プロジェクトの要件に応じて変更する必要があります。

react-app-rewire モジュールを使用すると、Create React App のビルド設定をカスタマイズできます。このモジュールを使用して、publicPath オプションを設定し、カスタム PUBLIC_URL を指定できます。

ビルドスクリプトをカスタマイズする

Create React App のデフォルトのビルドスクリプトを置き換えて、カスタムビルドスクリプトを使用できます。カスタムスクリプトでは、webpack API を使用して publicPath オプションを設定し、カスタム PUBLIC_URL を指定できます。

クラウドホスティングサービスを使用する

Vercel や Netlify などのクラウドホスティングサービスを使用すると、カスタムドメインとカスタム URL パスを使用してアプリケーションをデプロイできます。これらのサービスは、通常、アプリケーションのビルドプロセス中に PUBLIC_URL を自動的に設定します。

各方法の比較

最適な方法の選択

最適な方法は、プロジェクトの要件とスキルレベルによって異なります。

• 簡単な方法を求めている場合は、環境変数を使用する または homepage フィールドを使用する 方法がおすすめです。
• より多くの制御が必要な場合は、eject を使用する または ビルドスクリプトをカスタマイズする 方法がおすすめです。
• クラウドホスティングサービスを使用している場合は、クラウドホスティングサービスを使用する 方法がおすすめです。