できない.dev

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

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

公開: 更新:

症状できない
npx vite build
…
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

2026-10-08 に node:20(Vite 8.3.3 / Node.js 20.20.2) で実際に打って取った出力。検証環境の詳細

要約

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.js 20.20.2 / npm 10.8.2 / Python 3.11.2 / 2026-10-08 検証(ほか 2 件)
検証日
実行環境
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 を合わせて再ビルド

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

そのあと再ビルドし、preview で開き直す。

npm run build
npm run preview

ルート配信(独自ドメイン直下)なら、base: '/' のままでよい。
配信先のパスに合わせるのが原則だ(公式: 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)でキャッシュごと破棄する。

よくある原因

  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 が合わない。