After a frontend release you see intermittent white screens: the page is blank, the console reports ChunkLoadError, and a refresh or two fixes it. The root cause is version mismatch of build artifacts — the user's browser still holds the old HTML, but the old hashed assets it references were already overwritten by the new release. Vite itself is a good tool: zero-config builds, content-hashed assets, fast — but nobody teaches these deployment details, and one pitfall costs hours of debugging. This guide walks "install vite → build → deploy without white screens" end to end; all commands measured and copy-pasteable.

Use it when:

• You want to build frontend source into deployable artifacts (npx vite build);
• You are diagnosing intermittent white screens after a release (ChunkLoadError: old hashed asset 404);
• You want content-hashed assets (cache-friendly; changes only update what changed);
• You are using the build side of combo-web-deploy-verify (vite-deploy + playwright-mcp): build first, then let an agent assert with a browser.

Don't use it when: SSR/server-rendering scenarios (vite is a build tool; SSR needs build.ssr mode; this entry covers static SPA deployment only).

China network reality: npm direct access is slow — explicitly use --registry=https://registry.npmmirror.com (measured: 12 packages in 7s).

# Source: Trove detailed guide · verified 2026-08-31
npm install --save-dev vite --registry=https://registry.npmmirror.com

Expected output: vite 8.x installed into node_modules (8.2.2 measured on re-test 2026-08-31; 5.4.21 at collection)

Prerequisites: Node >= 18 (node v22 measured here); npm.

Verify after install:

• vite present in node_modules (8.2.2 measured 2026-08-31; 5.4.21 at collection);
• npx vite --version runs.

Install variants (deep dive)

npm installs vite (devDependency); npx vite build outputs dist/ (index.html + assets/*-<hash>.js/css). Content-hashed assets are naturally cache-friendly; but a wrong release order causes white screens:

• Version mismatch: old HTML + new assets → old hashed chunk 404 → ChunkLoadError → white screen;
• Correct order: upload new assets first, then update index.html (keep old assets for one release cycle);
• nginx trap: try_files must not swallow static 404s — match real files first, then fall back to index.html, otherwise the white screen is masked as "loaded fine but content empty".

Key concepts:

• content hash: file content change → filename hash change;
• ChunkLoadError: loading an old hashed chunk 404s (version mismatch);
• dist/: the build output directory.

What it touches after install: node_modules + package.json (devDependency); build output writes to dist/.

Step 1: build

# Source: Trove detailed guide · verified 2026-08-31
npx vite build

Expected output: dist/ with index.html + assets/*-<hash>.js/css (content hash; measured v8.2.2: built in 38ms, dist/assets/index-DaJps1dT.js)

If stuck:

• build errors → locate via the log (dependencies/syntax/paths); reproduce locally with dev (vite dev) first, then fix.

Step 2: local development (dev server, instant reload on edit)

# Source: Trove detailed guide · verified 2026-08-31
npx vite dev --host 0.0.0.0 --port 5173

Expected output: VITE v8.2.2 ready in ~200 ms + Local: http://localhost:5173/ (measured 2026-09-01: port fixed successfully, page returns HTML with /@vite/client injected; after editing src/main.js the log shows page reload and the browser auto-refreshes)

Note (measured pitfall): with a loopback host (localhost / 127.0.0.1), vite 8.2.2 ignores the fixed port and picks a random one — measured --host 127.0.0.1 --port 25273 actually listening on a random port. To fix the port use --host 0.0.0.0 --port <port> (other LAN devices can also reach it; for local-only use, still visit localhost).

If stuck:

• port is not the one you set → loopback host randomization pitfall; switch to 0.0.0.0;
• page won't open → confirm host/port match the address you visit.

Step 3: preview the build output (simulate production before deploy)

# Source: Trove detailed guide · verified 2026-08-31
npx vite preview --host 0.0.0.0 --port 4173

Expected output: Local: http://localhost:4173/, serving the dist/ artifacts (measured 2026-09-01: port fixed successfully, curl returns the same page as the build output; use it to simulate production and verify white-screen/path issues before deploying)

If stuck:

• preview differs from production → first confirm dist/ is from the latest build;
• white screen → open the console and check the exact 404 chunk filename; compare against the release batch to confirm version mismatch.

Step 4: deploy without white screens

# Source: Trove detailed guide · verified 2026-08-31
# Release order: 1) upload assets/*-<hash>.*  2) then update index.html (keep old assets one release cycle)
# nginx: try_files matches real static files first, then falls back to index.html (must not swallow 404s)

Expected output: after deploy, refreshing old users no longer white-screens (full plan: site docs)

If stuck:

• still white screen → open the browser console and check the exact 404 chunk filename; compare release batches to confirm version mismatch;
• nginx fallback swallowed a 404 → adjust try_files order (real files first, then index.html).

Same source as the tool-page matrix; full pairs, status and evidence at conflict matrix (co-install). Known relations:

• playwright-mcp × vite-deploy: members of combo-web-deploy-verify (two-stage split: build → browser assertion), judged possible-compatible — deploy writes build artifacts, verification writes to the browser, write surfaces don't overlap;
• Remaining pairs: write surfaces don't overlap (node_modules/dist/ vs each tool's independent surfaces), statically judged co-installable.

• Symptom: intermittent white screen after release → ChunkLoadError = old HTML + new assets version mismatch; assets first then entry, keep old assets one release cycle
• Symptom: dev port isn't the one you set → vite 8.2.2 loopback host port randomization pitfall; use --host 0.0.0.0 to fix it
• Symptom: nginx white screen masked → try_files matches real files first then falls back to index.html (must not swallow static 404s; measured: global fallback returns 200 HTML, a dedicated try_files $uri =404 for /assets/ returns a real 404)
• Symptom: npm install fails/slow → explicitly use --registry=https://registry.npmmirror.com
• Symptom: Node version error → confirm >= 18

Full four-section entries (symptom→cause→fix→evidence): site docs (if recorded)

# Source: Trove detailed guide · verified 2026-08-31
npm uninstall vite

Expected output: vite removed from node_modules/package.json (Removed package)

Note: residue after uninstall = the build output dist/ (delete manually if needed; it regenerates on the next build); other packages in node_modules are unaffected.

• Q: Intermittent white screen after release? A: ChunkLoadError = old HTML + new assets version mismatch → old hashed chunk 404. Release assets first then the entry, keep old assets one release cycle; nginx try_files matches real files first then falls back to index.html (measured: a dedicated try_files $uri =404 for /assets/ exposes missing chunks as real 404s).
• Q: What is the build hash? A: content hash — file content change → filename change, cache-friendly; changes only update what changed.
• Q: npm install fails? A: use the npmmirror registry (measured: 12 packages in 7s); confirm Node >= 18.
• Q: Used together with playwright-mcp? A: judged possible-compatible — deployment (build artifacts) and verification (browser) write surfaces don't overlap; combo "web deploy verify": site docs.
• Q: Where do I report issues? A: install/uninstall issues go through this entry's feedback; project issues go to the author repo.

• Version: 5.0~8.2 (5.4.21 at collection; 2026-08-31 full-chain re-test on major 8.2.2 passed). Content-hash and anti-white-screen conclusions don't depend on the vite version and hold under 8.2.2.
• Environment: Node >= 18 + npm (node v22 measured here).
• Network: npm via npmmirror registry (measured: 12 packages in 7s).
• Write surface: node_modules + package.json; build output dist/.
• Deployment: assets first then entry; keep old assets one release cycle; nginx try_files must not swallow static 404s.
• Co-install: possible-compatible with playwright-mcp (combo-web-deploy-verify member).

• Sources: official project docs (English) + local measurements (2026-08-29/31, 09-01)
• Entry signature: vite deploy white screen | ChunkLoadError | frontend build deploy | vite build artifacts | 404 after refresh

• Measured: local repro log 2026-08-31 (install + CLI + build + hashed asset references consistent); local repro log 2026-09-01 (dev/preview fixed ports + loopback randomization repro + HMR trigger); local repro log 2026-08-29 (install + build + ChunkLoadError repro)
• Not tested: real production deployment shapes (depend on the deployment environment); long-running dev mode (as projects need); SSR build mode.

Third-party tutorials are not individually verified; check against this page and official docs.

• 官方层（npm registry readme + vite.dev 文档，v8.2.2）：Vite 构建与部署用法 [官方文档 · Vite 官方 · 2026-08-31（包 8.2.2）]
  官方用法全解——零配置构建（vite build 产出 dist/ + 内容 hash 资产）、开发服务器（vite dev）、部署要点（先传资源后更新 index.html、nginx try_files 不能吞静态 404）、ChunkLoadError 排查（版本错位）