vite-deploy

你会遇到什么

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

• 你要把前端源码构建成可部署产物（npx vite build）；
• 你要排查发布后偶发白屏（ChunkLoadError：旧 hash 资源 404）；
• 你要内容 hash 资产（缓存友好，改文件只更新改动）。

什么时候别用：SSR/服务端渲染场景（vite 本身是构建工具，按项目形态选模式）。

本文路径：快速修复（30 秒一段命令）→ 一步步来（可跳读）→ 怎么确认修好了（成功判据）。赶时间直接跳到「快速修复」。

为什么会这样

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 步：装 vite

讲解：vite 是构建期工具，装 devDependency（--save-dev）不污染生产依赖。国内 npm 直连慢，显式指定 npmmirror 镜像（实测 7s 装 12 包）。需要 Node >= 18（本环境 node v22 实测）。

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_modules 出现 vite（2026-08-31 重测实测 8.2.2；收录实测 5.4.21）；
• npx vite --version 可运行。

卡住怎么办：

• npm 慢/超时 → 确认命令带 --registry=https://registry.npmmirror.com；
• Node 版本 → 确认 >= 18。

第 2 步：构建

讲解：npx vite build 产出 dist/（index.html + assets/*-<hash>.js/css）。内容 hash：改文件只更新改动，缓存友好。

npx vite build

预期输出: dist/ 产出 index.html + assets/*-<hash>.js/css（内容 hash）

装好确认：

• dist/ 存在且 assets/ 文件名带 hash；
• 构建日志无报错。

卡住怎么办：

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

第 3 步：部署防白屏

讲解：发布后偶发白屏 = 用户打开旧 HTML（缓存），页面里的旧 hash chunk 已被新发布覆盖 → 404 → ChunkLoadError。三条规则：先资源后入口；旧资源保留一个发布周期；nginx try_files 不能吞静态 404（先匹配真实文件再回退 index.html）。

# 发布顺序：1) 上传 assets/*-<hash>.*  2) 再更新 index.html（旧资源保留一个发布周期）
# nginx：try_files 先匹配真实静态文件，再回退 index.html（不能吞 404）

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

装好确认：

• 新部署后，旧页面刷新能拿到新入口（或至少不 404 白屏）。

卡住怎么办：

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

怎么确认修好了

一条命令 + 一个检查，装好没装好立刻见分晓：

npx vite build

预期输出: 构建成功，dist/ 产出 index.html + assets/*-<hash>.js/css

• 构建产物里 assets/ 文件名带内容 hash（如 index-a1b2c3.js）；
• 部署后：新发布先上传 assets/ 再更新 index.html，旧用户刷新不再白屏（ChunkLoadError 消失）；
• 复现验证：临时把 index.html 里引用的旧 hash 文件名改错，刷新应看到 404/ChunkLoadError（证明版本错位机制成立）——完整复现证据见 实测复现日志（2026-08-29）。

其它环境的表现（常见变体）

• Node 版本：>= 18 必需（本环境 node v22 实测）；旧 Node 装 vite 5 会报 engine 警告或安装失败。
• npm 源：国内直连慢，显式 --registry=https://registry.npmmirror.com（实测 7s 装 12 包）。
• 部署平台：nginx 需 try_files 先真实文件后 index.html；纯静态托管（GitHub Pages 等）天然按文件发布，仍要遵守「先资源后入口」。
• CI 环境：构建产物 hash 每次不同，缓存保留一个发布周期即可，无需手动清 CDN（内容 hash 自动失效旧文件）。
• SSR 项目：vite 构建模式不同（SSR 需 build.ssr），本条目仅覆盖纯静态 SPA 部署。

日常使用

启动与入口

• 构建：npx vite build；
• 本地开发：npx vite dev（实测，见操作二）；
• 预览产物：npx vite preview（实测，见操作三）。

常用操作

操作一：构建产物

npx vite build

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

操作二：本地开发（dev server，改代码即时生效）

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：25173 端口固定成功，页面返回注入 /@vite/client 的 HTML；改 src/main.js 后日志出现 page reload src/main.js，浏览器自动刷新）

注意（实测坑）：vite 8.2.2 在 host 为回环（localhost / 127.0.0.1）时固定端口会失效并改用随机端口——实测 --host 127.0.0.1 --port 25273 实际监听随机端口。需要固定端口时用 --host 0.0.0.0 --port <端口>（局域网内其他设备也可访问；只本机用仍访问 localhost）。 操作三：预览构建产物（不重新构建，直接跑 dist/）

npx vite preview --host 0.0.0.0 --port 4173

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

数据与目录

• 产物：dist/（index.html + assets/）；
• 依赖：node_modules + package.json（devDependency）。

卸载与清理

note: npm 卸载 devDependency；dist/ 构建产物按需清理

npm uninstall vite

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

依赖警告

• 版本：[5.0, 8.2] 区间（收录实测 5.4.21；2026-08-31 大版本 8.2.2 构建链完整重测通过：装包 + CLI + build + hash 资产引用一致，证据）。内容 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（部署写构建产物、验证写浏览器，写面不重叠）；组合包「网页部署验证」见 站内文档。

FAQ（常见问题）

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