できない.dev

vite preview がブランク（真っ白）で表示できない

vite preview がブランクになる原因の大半は base 設定漏れによるアセットの 404。
GitHub Pages 等のサブパス配信時は vite.config.ts の base を本番値に揃える必要がある。

#preview #build #base #deploy

公開: 更新:

実行例あり（2026-10-08 に実環境で検証）

要約

vite preview で開いた画面が真っ白で、DevTools の Network タブを見るとアセット（/assets/index-xxx.js 等）が 404 か MIME エラーになっている — というのは vite.config.ts の base 設定漏れがほぼ確実です。
本番配信先がサブパス（GitHub Pages の /repo-name/ 等）なら base を合わせて再ビルドします。

実行例

base を既定の / のままビルドして dist/ を /repo-name/ の下で配信すると、HTML は 200 で返るのに JS アセットは 404 になった。base を /repo-name/ に設定して再ビルドすると、index.html の src が /repo-name/assets/ 以下を指すようになり、アセットも 200 で返っている。

$ npx vite build
vite v8.3.3 building client environment for production...
transforming...
✓ 4 modules transformed.
rendering chunks...
computing gzip size...
dist/index.html                0.15 kB │ gzip: 0.14 kB
dist/assets/index-IW7W9BLY.js  0.72 kB │ gzip: 0.41 kB
 
✓ built in 47ms
$ grep -o 'src="[^"]*"' dist/index.html
src="/assets/index-IW7W9BLY.js"
$ curl -s -o /dev/null -w '%{http_code}\n' http://localhost:4000/repo-name/
200
$ curl -s -o /dev/null -w '%{http_code}\n' http://localhost:4000/assets/index-IW7W9BLY.js
404
$ npx vite build
vite v8.3.3 building client environment for production...
transforming...
✓ 4 modules transformed.
rendering chunks...
computing gzip size...
dist/index.html                0.16 kB │ gzip: 0.14 kB
dist/assets/index-IW7W9BLY.js  0.72 kB │ gzip: 0.41 kB
 
✓ built in 40ms
$ grep -o 'src="[^"]*"' dist/index.html
src="/repo-name/assets/index-IW7W9BLY.js"
$ curl -s -o /dev/null -w '%{http_code}\n' http://localhost:4000/repo-name/assets/index-IW7W9BLY.js
200

— 2026-10-08 時点の出力

検証環境

検証日
実行環境
node:20 Debian GNU/Linux 12 (bookworm)
バージョン
  • Node.js 20.20.2
  • npm 10.8.2
  • Python 3.11.2
  • Git 2.39.5
  • Vite 8.3.3

この記事の「実行例」は、上記の環境で実際にコマンドを実行して得られた出力をそのまま掲載しています。 再現手順はリポジトリの検証スクリプトとして管理し、定期的に再実行して出力を更新しています。

よくある原因

  1. base が / のまま: vite.config.ts の base を指定しないとアセットは絶対パス /assets/... で出力されるが、サブパス配信先では 404 になる。
    preview もこれを再現する。
  2. 古い dist/ を見ている: base を書き換えたあと vite build を流し直していない。
    preview は dist/ をそのまま静的配信するだけなので変更が反映されない。
  3. Router 側の basename がずれている: アセットは読めるが画面が真っ白なら、React Router の <BrowserRouter basename="..."> や Vue Router の createWebHistory("...") が base と食い違ってルーティングに失敗している。
  4. Service Worker のキャッシュ: 過去にデプロイした SW が古い index.html を返してアセットの hash が合わない。

解決策

1. base を合わせて再ビルド

import { defineConfig } from "vite";
 
export default defineConfig({
  base: "/repo-name/",
});

そして再ビルド + preview。

npm run build
npm run preview

ルート配信（独自ドメイン直下）なら base: '/' のままで OK。
配信先のパスに合わせるのが原則です（公式: Public base path（新しいタブで開く））。

2. Router を import.meta.env.BASE_URL 起点に

import { BrowserRouter } from "react-router-dom";
 
<BrowserRouter basename={import.meta.env.BASE_URL}>
  {/* ... */}
</BrowserRouter>;

base を書き換えたときに片方だけ忘れる事故を防げます。

3. Service Worker を解除

DevTools の Application タブ → Service Workers → Unregister を実行し、ハードリロード（Cmd/Ctrl + Shift + R）でキャッシュごと破棄します。

この記事は役立ちましたか？