前端上线后偶发白屏：用户打开页面一片白，控制台报 ChunkLoadError，刷新几次又好了。根子是构建产物的版本错位——用户浏览器里还是旧 HTML，页面引用的旧 hash 资源已经被新发布覆盖。Vite 本身是好工具：零配置构建、内容 hash 资产、快，但这些部署细节没人讲，踩一次坑就要排查半天。这篇指南把「装 vite → 构建 → 部署防白屏」完整走一遍，命令全部实测可复制。

什么时候用：

• 你要把前端源码构建成可部署产物（npx vite build）；
• 你要排查发布后偶发白屏（ChunkLoadError：旧 hash 资源 404）；
• 你要内容 hash 资产（缓存友好，改文件只更新改动）；
• 组合包 combo-web-deploy-verify（vite-deploy + playwright-mcp）的构建侧：先构建、再让 agent 用浏览器断言。

什么时候别用：SSR/服务端渲染场景（vite 本身是构建工具，SSR 需 build.ssr 模式，本条目仅覆盖纯静态 SPA 部署）。

国内网络的关键：npm 直连慢，显式带 --registry=https://registry.npmmirror.com（实测 7s 装 12 包）。

# 来源: Trove 详细指南 · 验证于 2026-08-31
npm install --save-dev vite --registry=https://registry.npmmirror.com

预期输出: vite 8.x 装入 node_modules（2026-08-31 重测实测 8.2.2；收录实测 5.4.21）

前置条件：Node >= 18（本环境 node v22 实测）；npm。

装好确认：

• node_modules 出现 vite（2026-08-31 重测实测 8.2.2；收录实测 5.4.21）；
• npx vite --version 可运行。

npm 装 vite（devDependency），npx vite build 产出 dist/（index.html + assets/*-<hash>.js/css）。内容 hash 资产天然缓存友好；但发布顺序错了就白屏：

• 版本错位：旧 HTML + 新资源 → 旧 hash chunk 404 → ChunkLoadError → 白屏；
• 正确顺序：先上传新资源，再更新 index.html（旧资源保留一个发布周期）；
• nginx 陷阱：try_files 不能吞静态 404——必须先匹配真实文件，再回退 index.html，否则白屏被掩盖成「加载成功但内容空」。

关键概念：

• content hash：文件内容变化 → 文件名 hash 变化；
• ChunkLoadError：加载旧 hash chunk 404（版本错位）；
• dist/：构建产物目录。

装完它动哪里：node_modules + package.json（devDependency）；构建产物写 dist/。

第 1 步：构建

# 来源: Trove 详细指南 · 验证于 2026-08-31
npx vite build

预期输出: dist/ 产出 index.html + assets/*-<hash>.js/css（内容 hash；实测 v8.2.2：built in 38ms，dist/assets/index-DaJps1dT.js）

卡住怎么办：

• 构建报错 → 按日志定位（依赖/语法/路径），先本地 dev（vite dev）复现再修。

第 2 步：本地开发（dev server，改代码即时生效）

# 来源: Trove 详细指南 · 验证于 2026-08-31
npx vite dev --host 0.0.0.0 --port 5173

预期输出: VITE v8.2.2 ready in ~200 ms + Local: http://localhost:5173/（实测 2026-09-01：端口固定成功，页面返回注入 /@vite/client 的 HTML；改 src/main.js 后日志出现 page reload，浏览器自动刷新）

注意（实测坑）：vite 8.2.2 在 host 为回环（localhost / 127.0.0.1）时固定端口会失效并改用随机端口——实测 --host 127.0.0.1 --port 25273 实际监听随机端口。需要固定端口时用 --host 0.0.0.0 --port <端口>（局域网内其他设备也可访问；只本机用仍访问 localhost）。

卡住怎么办：

• 端口不是自己指定的 → 回环 host 随机化坑，改用 0.0.0.0；
• 页面打不开 → 确认 host/port 与访问地址一致。

第 3 步：预览构建产物（部署前模拟线上）

# 来源: Trove 详细指南 · 验证于 2026-08-31
npx vite preview --host 0.0.0.0 --port 4173

预期输出: Local: http://localhost:4173/，访问即 dist/ 产物（实测 2026-09-01：端口固定成功，curl 返回与 build 产物一致的页面；部署前用它模拟线上环境，验证白屏/路径问题）

卡住怎么办：

• 预览与线上不一致 → 先确认 dist/ 是最新 build 的产物；
• 白屏 → 打开控制台看具体 404 的 chunk 文件名，对照发布批次确认版本错位。

第 4 步：部署防白屏

# 来源: Trove 详细指南 · 验证于 2026-08-31
# 发布顺序：1) 上传 assets/*-<hash>.*  2) 再更新 index.html（旧资源保留一个发布周期）
# nginx：try_files 先匹配真实静态文件，再回退 index.html（不能吞 404）

预期输出: 部署后旧用户刷新不再白屏（完整方案见 站内文档）

卡住怎么办：

• 仍白屏 → 打开浏览器控制台看具体 404 的 chunk 文件名，对照发布批次确认版本错位；
• nginx 回退吞了 404 → 调整 try_files 顺序（先真实文件后 index.html）。

与工具页矩阵同源；完整对子、状态与证据见 冲突对子（共装矩阵）。已知关联：

• playwright-mcp × vite-deploy：组合包 combo-web-deploy-verify 成员（构建 → 浏览器断言两段分工），判定 possible-compatible——部署写构建产物、验证写浏览器，写面不重叠；
• 其余对子：写面不重叠（node_modules/dist/ vs 各工具独立写面），静态判定可共存。

• 症状：发布后偶发白屏 → ChunkLoadError = 旧 HTML + 新资源版本错位；先资源后入口，旧资源保留一个发布周期
• 症状：dev 端口不是自己指定的 → vite 8.2.2 回环 host 端口随机化坑，用 --host 0.0.0.0 固定
• 症状：nginx 部署白屏被掩盖 → try_files 先匹配真实文件再回退 index.html（不能吞静态 404；实测：全局兜底返回 200 HTML，assets 目录单独 try_files $uri =404 返回真 404）
• 症状：npm 装不上/慢 → 显式 --registry=https://registry.npmmirror.com
• 症状：Node 版本报错 → 确认 >= 18

四段式全文（症状→原因→解法→验证证据）：站内文档（如已收录）

# 来源: Trove 详细指南 · 验证于 2026-08-31
npm uninstall vite

预期输出: vite 从 node_modules/package.json 移除（Removed package）

注意：卸载后残留项 = 构建产物 dist/（按需手动删，不影响下次构建重新生成）；node_modules 内其它包不受影响。

• 问：发布后偶发白屏？答：ChunkLoadError = 旧 HTML + 新资源版本错位 → 旧 hash chunk 404。发布先资源后入口，旧资源保留一个发布周期；nginx try_files 先匹配真实文件再回退 index.html（实测：assets 目录单独 try_files $uri =404，缺失 chunk 返回真 404 可定位）。
• 问：构建产物 hash 是什么？答：内容 hash——文件内容变化 → 文件名变化，缓存友好；改文件只更新改动。
• 问：npm 装不上？答：用 npmmirror 镜像（实测 7s 装 12 包）；确认 Node >= 18。
• 问：和 playwright-mcp 一起用？答：判定 possible-compatible——部署（构建产物）与验证（浏览器）写面不重叠；组合包「网页部署验证」见 站内文档。
• 问：使用问题向谁反馈？答：本市场安装/卸载问题走条目反馈入口；项目自身问题请向作者仓库反馈。

• 版本：5.0~8.2（收录实测 5.4.21；2026-08-31 大版本 8.2.2 构建链完整重测通过）。内容 hash 与防白屏结论不依赖 vite 版本，8.2.2 下成立。
• 环境：Node >= 18 + npm（本环境 node v22 实测）。
• 网络：npm 用 npmmirror 镜像（实测 7s 装 12 包）。
• 写面：node_modules + package.json；构建产物 dist/。
• 部署：先资源后入口；旧资源保留一个发布周期；nginx try_files 不能吞静态 404。
• 共装：与 playwright-mcp 判定 possible-compatible（combo-web-deploy-verify 成员）。

• 条目签名：vite 部署白屏 | ChunkLoadError | 前端构建 部署 | vite build 产物 | 刷新后 404

• 实测：实测复现日志（2026-08-31）（装包 + CLI + build + hash 资产引用一致）；实测复现日志（2026-09-01）（dev/preview 固定端口 + 回环随机化坑复现 + HMR 触发）；实测复现日志（2026-08-29）（安装 + 构建 + ChunkLoadError 复现）
• 未实测：生产环境真实部署形态（按部署环境而定）；dev 模式长跑（按项目需要）；SSR 构建模式。

第三方教学未逐条实测，仅供学习；有出入以本页与官方文档为准。

• 官方层（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 排查（版本错位）