ReactをNetlifyにデプロイする方法

ReactアプリをNetlifyにデプロイする方法は、静的ホスティングの中でもかなり扱いやすい部類に入る。特にViteで作ったReactアプリは、ビルド結果が dist にまとまりやすく、GitHub連携を使えば push ごとに自動デプロイまでつなげやすい。重要なのは、単に公開するだけではなく、「どの方法でデプロイするか」「本番ビルドが通るか」「環境変数をどう管理するか」「SPAルーティングで404を出さないか」を先に整理しておくこと。この記事では、Vite + Reactを前提に、ローカル準備からNetlify公開、よくあるエラーまでを順番にまとめる。

最初に理解しておくこと

ReactをNetlifyへデプロイする方法は大きく2つある。
・GitHubなどのGitリポジトリをNetlifyに接続して自動デプロイする方法
・ローカルでビルドしたファイルをNetlifyへ手動デプロイする方法
継続運用を考えるならGit連携の方が扱いやすい。
理由は、
・pushごとに自動でデプロイできる
・変更履歴が残る
・プレビュー環境を作りやすい
から。
一方で、まず今のアプリを手早く公開したいだけなら、手動デプロイでも始めやすい。

前提になる開発環境を確認する

Netlifyへ上げる前に、ローカルでReactアプリが正常に動いていることが前提になる。最低限、次を確認する。
・Node.js が入っている
・npm または yarn / pnpm が使える
・npm run dev で開発サーバーが起動する
・npm run build が通る
特に重要なのは build が通ること。開発サーバーが動いていても、本番ビルドで失敗することは珍しくない。

Vite + React プロジェクトの基本確認

Viteで作ったReactアプリなら、まず package.json の scripts を確認する。
一般的には次のような形になっている。

{
“scripts”: {
“dev”: “vite”,
“build”: “vite build”,
“preview”: “vite preview”
}
}

Netlifyでは通常、この build が実行され、その結果として生成された dist ディレクトリが公開対象になる。
この流れをローカルで理解しておくと、Netlify側の設定が読みやすい。

ローカルで本番ビルドを確認する

まずはローカルで本番ビルドが成功するか確認する。

npm run build

成功すると通常は dist ディレクトリが生成される。
さらにローカルでビルド結果を確認したいなら次を実行する。

npm run preview

ここで起こりやすいエラー条件は次の通り。
・importパスが間違っている
・開発中は見えていなかった構文エラーがbuildで出る
・環境変数が定義されていない
・依存パッケージが不足している
Netlifyでのビルド失敗の多くは、この段階で再現できる。

デプロイ前に整理しておくファイル

公開前に最低限見直しておくと良いのは次の点。
・node_modules をコミットしていない
・.gitignore が適切
・.env.local を誤って公開していない
・デバッグ用コードを消している
・API接続先を本番前提で整理している
特に環境変数まわりは重要で、ローカル用URLをコードに直書きしたままだと、デプロイ後に通信だけ失敗しやすい。

GitHub連携でデプロイする方法

最も分かりやすいのは、GitHubへコードをpushしてNetlifyへ接続する流れ。
大まかな手順は次の通り。
・ReactプロジェクトをGitHubへpushする
・Netlifyへログインする
・「Add new site」からImportを選ぶ
・対象リポジトリを接続する
・Build command と Publish directory を確認してデプロイする
一度つながれば、その後は push ごとに再デプロイされるため、継続運用がかなり楽になる。

GitHubへ初回pushする手順

まだGit管理していない場合は、最初にローカルプロジェクトをリポジトリ化してpushする。

git init
git add .
git commit -m “first commit”

GitHub上で空リポジトリを作成したあと、次のようにpushする。

git remote add origin https://github.com/your-name/your-repo.git
git branch -M main
git push -u origin main

ここで起こりやすいエラー条件は、
・node_modules を含めてしまう
・認証エラーでpushできない
・既存リポジトリの履歴と衝突する
・mainブランチ名が違う
といったもの。

NetlifyでBuild commandとPublish directoryを設定する

Vite + React の一般的な構成では、Netlify側の設定は次のようになることが多い。
・Build command: npm run build
・Publish directory: dist
これがズレると、ビルドには成功しても公開対象が空だったり、404だけが出たりする。
特に初心者がやりやすいのは、Publish directoryを src やプロジェクトルートにしてしまうミス。
公開するのは必ずビルド後の成果物ディレクトリになる。

手動デプロイする方法

Git連携を使わず、手動でデプロイすることもできる。
その場合は、ローカルでビルドした dist ディレクトリをNetlifyへアップロードする流れになる。
まずビルドする。

npm run build

その後、生成された dist をNetlifyへドラッグ&ドロップ、または手動アップロードする。
この方法は、まず公開だけ試したいときには便利だが、更新のたびに手作業になるため、継続運用ではGit連携の方が扱いやすい。

環境変数の設定方法

ReactアプリでAPIのURLや外部サービスキーを使うなら、Netlify側で環境変数を設定する必要がある。
Viteではクライアント側で使う環境変数名に VITE_ プレフィックスが必要になることが多い。

VITE_API_BASE_URL=https://api.example.com

アプリ側では次のように参照する。

const apiBaseUrl = import.meta.env.VITE_API_BASE_URL;

ローカルでは .env.local、Netlifyでは管理画面の環境変数設定で管理する。
発生しやすいエラー条件は、
・VITE_ を付けていない
・ローカルでは読めるのにNetlify側へ未設定
・Preview用とProduction用の値を分けていない
というもの。

SPAのルーティングで404を防ぐ

React Routerなどを使ったSPAでは、/about や /users/1 のようなURL直打ちで404になることがある。
これはNetlifyがそのURLに対応する静的ファイルを探してしまうため。
この場合は、SPA用のリダイレクト設定を追加する必要がある。
Netlifyでは _redirects ファイルを使う構成が分かりやすい。

プロジェクトの public ディレクトリに _redirects を作成する。

/* /index.html 200

Viteでは public 配下のファイルがそのままビルド成果物へコピーされるため、この方法でSPAルーティングの404を避けやすい。
ルーティング付きのReactアプリではかなり重要な設定になる。

Netlify設定ファイルで管理する方法

GUIだけでなく、リポジトリ内に netlify.toml を置いて設定をコード管理する方法もある。
複数人開発や設定共有ではこちらの方が再現しやすい。

[build]
command = “npm run build”
publish = “dist”

この方法なら、Build command や Publish directory がダッシュボード依存にならず、リポジトリを見れば設定が分かる。
設定の属人化を減らしたい場合に向いている。

API接続先の切り替えを整理する

ローカルと本番でAPI接続先が違うなら、コード直書きではなく環境変数へ寄せる方が安全。
悪い例は次のようなもの。

const apiBaseUrl = ‘http://localhost:3000’;

改善例は次の通り。

const apiBaseUrl = import.meta.env.VITE_API_BASE_URL;

この形にしておくと、
・ローカルでは .env.local
・NetlifyのPreviewではPreview用設定
・本番ではProduction用設定
という分離がしやすい。
デプロイ後に「画面は出るが通信だけ失敗する」ときは、ここを疑う方が早い。

Preview環境と本番環境を分けて考える

Netlifyでは、Git連携するとブランチやPull Request単位でPreview環境を作りやすい。
そのため、実務では次のような分け方が扱いやすい。
・featureブランチ → Preview確認用
・mainブランチ → 本番反映用
この運用にすると、UIの確認、ルーティング確認、API疎通確認を本番前にしやすくなる。
特にReactのように見た目の確認が多いアプリでは、Preview URLの価値が大きい。

デプロイ後に確認するべきポイント

デプロイ成功後は、すぐに次を確認する。
・トップページが表示されるか
・主要ルートが直打ちで開けるか
・API通信が成功するか
・環境変数が反映されているか
・画像、CSS、JSが壊れていないか
・スマホ表示でも崩れていないか
「Netlify上でデプロイ成功」と「アプリが正常に使える」は別問題なので、公開後の確認は省かない方がよい。

よくあるエラーと発生条件

ReactをNetlifyへ上げるときによくある問題は次の通り。
・Build Failed
→ npm run build がローカルでも通っていない、依存不足、Nodeバージョン差
・トップは出るが深いURLで404
→ _redirects が無い
・APIだけ動かない
→ 環境変数未設定、接続先がローカルのまま、CORS問題
・画像やアセットが壊れる
→ パスの書き方、public配置ミス、base設定不整合
・手動デプロイでは動くのにGit連携で失敗
→ Build command や Publish directory の設定ズレ
・本番だけ値が違う
→ Preview と Production の環境変数を分けていない
デプロイの問題は、React自体よりも「ビルド」「環境変数」「SPAルーティング」に集まりやすい。

初心者向けの最短手順まとめ

最短でReactをNetlifyへ公開する流れは次の通り。
・ViteでReactアプリを作る
・npm install
・npm run build で本番ビルド確認
・GitHubへpush
・NetlifyでリポジトリをImport
・Build command を npm run build
・Publish directory を dist
・必要なら public/_redirects を追加
・環境変数を設定
・公開後に主要画面とAPI通信を確認
この流れで進めると、初回公開までの失敗をかなり減らしやすい。

まとめ

ReactをNetlifyにデプロイする方法は、Viteとの相性が良く、Git連携でも手動でも比較的始めやすい。
安定して運用するには、
・ローカルで npm run build を通す
・Build command と Publish directory を正しく設定する
・環境変数を整理する
・SPAの404対策を入れる
・PreviewとProductionを分けて考える
という流れを押さえるのが大事になる。
単に公開するだけなら簡単だが、実際に「壊れず運用できる状態」にするには、ビルド、ルーティング、環境変数の3点を最初から整えておく方が後で楽になる。