vite-deploy — Agent Guide

No conflict-matrix pairs for this tool yet.

# Vite Deploy — Agent Guide

name: vite-deploy ｜ version_range: 5.0~8.2｜ generated: 2026-08-29

title_en: Vite - Frontend Build & Deploy (hash assets, ChunkLoadError fix) ｜ desc_en: Zero-config frontend build tool with content-hashed assets; diagnose white-screen after deploy (version mismatch / ChunkLoadError).

Preflight

note: Requires Node >= 18 and npm (verified on node v22).

node --version && npm --version

Install

note: Use npmmirror registry in mainland China (verified: 12 packages in 7s).

npm install --save-dev vite --registry=https://registry.npmmirror.com

预期输出: vite 5.x installed (verified 5.4.21).

Build

npx vite build

预期输出: dist/ with index.html + assets/*-<hash>.js/css.

Problem: white screen after deploy (ChunkLoadError)

- Root cause: stale HTML + new assets = version mismatch; old hash chunk 404 on dynamic import.

- Fix order: deploy assets first, then entry HTML; keep old assets for one release cycle.

- nginx: try_files must not swallow static 404s (match real files before index.html fallback).

- Evidence: 实测复现日志（2026-08-29）

Dev server

note: verified 2026-09-01; loopback host (localhost/127.0.0.1) makes vite 8.2.2 ignore the fixed port - use --host 0.0.0.0 to pin it

npx vite dev --host 0.0.0.0 --port 5173

预期输出: `VITE v8.2.2 ready in ~200 ms` + `Local: http://localhost:5173/`; HMR on file change: `page reload src/main.js`

Preview built artifacts

note: serves dist/ without rebuilding; verified 2026-09-01

npx vite preview --host 0.0.0.0 --port 4173

预期输出: `Local: http://localhost:4173/`, serving dist/ output

Uninstall

npm uninstall vite

预期输出: vite removed from node_modules/package.json.

Source: vite-deploy · validated 2026-08-31 · v5.0~8.2

← Agent index