前阵子帮一个朋友排查线上问题他用 Vue 写的前端项目vue-cli build打包后部署到服务器本地开发一切正常一上线就出妖——页面初次打开还好刷新一下直接 404有的路由甚至白屏。更诡异的是同一个项目后来用vite build重写了一遍部署后居然还会遇到类似的刷新 404 和空白页问题。这其实不是某个工具的 Bug而是大多数前端单页应用SPA生产部署都会踩的经典组合坑。这篇文章就把这类问题的完整现象、根因、排查链路、vue-cli 和 vite 两个构建链路的修复方法以及服务器端配置一次讲透。不管你是刚接触部署的新人还是被线上问题折磨过的老手照着这篇文章的顺序排查基本都能把“刷新 404 / 弹窗 404 / 白屏”解决掉。1. 问题现象与典型场景刷新白屏和 404 弹窗的几种形态在给修复方案之前我建议先做一步“对号入座”。因为“刷新或弹窗 404页面空白”这句话其实覆盖了好几种不同的情况原因和解决方案不完全一样。很多人找不到问题根源就是因为没分清自己属于哪一种。1.1 最常见的三种形态形态一页面首次访问完全正常按下 F5 刷新后浏览器整页变成 404。地址栏里的路径比如/user/list服务器直接返回了一个 404 页面白屏是因为页面内容压根没渲染出来。这种基本可以锁定为前端用了 history 路由模式服务器却没有配置对应的“回退”规则。形态二刷新后页面白屏Network 面板里 JS 和 CSS 资源出现一大片 404。页面主文档可能还是 200但引用的/assets/index.js找不到入口脚本都没加载成功Vue 自然没机会挂载到页面上。这种情况通常是构建产物里的资源路径前缀publicPath/base和实际部署路径不一致造成的。形态三页面能打开但点击某些模块时弹出一个 404 错误或者页面切过去变空白。这种情况常见于路由懒加载的场景。主包的脚本没问题但按需加载的 chunk 文件在请求时 404导致对应组件渲染不出来有的项目会在全局错误处理里弹出一个“资源加载失败”或 404 提示。1.2 先分清是“路由 404”还是“资源 404”这个区分很重要因为修复手段完全不同。我一般让同事先打开浏览器开发者工具刷新页面后看 Network 面板再对照控制台的报错信息。现象主文档请求静态资源请求更接近的根因刷新后整页 404返回 404响应内容是服务器错误页没有请求或全部未加载history 路由缺少服务器回退白屏控制台大量资源加载失败返回 200HTML 正常/assets/xxx.js返回 404publicPath/base与部署路径不匹配个别路由白屏/弹窗 404返回 200动态 chunk 文件返回 404chunk 路径拼接错误或服务器清理了旧文件2. 根因拆解路由模式、资源路径与服务器回退三者如何配合要彻底搞懂这个问题不能只背解决方案。SPA 部署涉及三个关键环节任何一个掉链子都会出现上面说的现象。2.1 前端路由的两种模式hash 和 history前端路由有两种主流实现模式hash 模式URL 形如https://example.com/#/user/list。井号后面的内容不会发送到服务器浏览器地址变化时前端框架自己监听并渲染。服务器只需要把index.html返回给任意请求不需要额外配置。缺点就是 URL 不太好看。history 模式URL 形如https://example.com/user/list。这是真实路径浏览器把请求发送给服务器服务器如果找不到这个文件自然就返回 404。前端框架需要借助服务器端的“回退”规则让所有非静态文件的请求都返回index.html再由前端路由接管。可以这样理解hash 模式是每个页面都带一个书签不管服务器看到什么都先把书的封皮递给你history 模式是浏览器报出精确的章节名服务器需要判断“这本书虽然没这一章但我应该把封皮递给你让前端自己翻到那一页”。如果服务器没有这个判断就直接说“本书不存在”。2.2 构建工具的资源路径publicPath与base无论是 vue-cli 还是 vite构建后的index.html里都会引用打包生成的 JS/CSS 文件。这些资源地址的前缀由构建配置决定vue-cli 对应的是publicPath默认值/vite 对应的是base默认值也是/当你把项目部署在域名根目录时/没问题。但如果部署到子路径比如https://example.com/admin/而构建时publicPath还是/那么index.html里会写成/assets/index.js浏览器会去https://example.com/assets/index.js请求自然 404。2.3 服务器回退规则fallback服务器需要配置一条规则当请求路径在磁盘上找不到对应文件时返回index.html的入口内容而不是返回 404。Nginx 里最常见的是try_files $uri $uri/ /index.html;一些静态托管平台也有类似功能名称可能是“SPA fallback”“Rewrite Rules”之类。3. 一条完整的排查链路从浏览器控制台到服务器配置逐层定位很多同学遇到问题第一反应是搜“vue 部署白屏怎么解决”然后照着别人的配置改一堆改完还是不行。我自己的经验是不要急着改配置先按下面的链路把问题“定位死”再动手。3.1 第一步打开 Network 面板判断主文档和资源的状态刷新生产环境页面按下 F12进入 Network 面板勾选“Disable cache”后再刷新一次。重点看两个位置最顶上的主文档请求一般是document类型状态码是 200 还是 404页面里的 JS/CSS 文件请求路径是什么样的状态码是不是 404。如果主文档 404往往是服务器回退没配。如果主文档 200 但资源 404那就是资源路径与部署路径不匹配。3.2 第二步用 curl 直接请求深层路径在终端里模拟浏览器请求直接访问一个子路由地址curl -i https://example.com/user/list重点看响应头里的Content-Type。如果你看到的是text/html说明服务器至少把index.html内容返回回来了回退规则大概率生效。如果你看到的是 404 状态码或者返回的是 Nginx 默认错误页那问题就在服务器配置。3.3 第三步检查构建产物里的资源路径本地查看dist/index.html的内容看script和link标签里引用资源的地址grep -Eo (src|href)[^]* dist/index.html如果输出是/assets/index.js说明构建时资源前缀是根路径如果输出是./assets/index.js说明用了相对路径如果输出是/admin/assets/index.js说明用了子路径前缀。拿到这个结果后对照一下生产环境的实际访问路径基本就能定位到publicPath/base是不是配错了。3.4 第四步检查服务器配置查看 Nginx 的配置文件重点看location块里有没有try_filesroot指向的目录是否就是前端dist目录。如果是静态托管平台去后台找“路由重写”相关设置。我整理了一张快速定位表方便排查时对照症状主文档状态资源状态最可能的根因优先检查项深层路由刷新 404404未加载服务器无回退规则try_files/ 平台 rewrite页面白屏资源 404200404publicPath/base写错构建产物中的资源前缀子路径部署全挂404 或资源 404404部署路径与配置不一致站点访问路径 vs 构建前缀新版本刚发就白屏200个别旧 chunk 404浏览器缓存旧index.html入口文件缓存策略4. vue-cli build 场景的修复方法配置、部署、验证一条龙先看vue-cli构建的 Vue 2 / Vue 3 项目。这里说的方案适用于使用webpack打包的 Vue 项目。4.1 第一步确认你的路由模式打开路由配置文件查看是createWebHistory还是createWebHashHistory// Vue Router 4 写法 const router createRouter({ // history: createWebHistory(import.meta.env.BASE_URL), // history 模式 history: createWebHashHistory(import.meta.env.BASE_URL), // hash 模式 routes })如果是 history 模式那么服务器回退规则几乎是必须的。如果你没法控制服务器配置比如只能在纯静态空间部署那就老老实实改用 hash 模式这是成本最低的兜底方案。4.2 第二步配置 vue.config.js 的 publicPath打开项目根目录的vue.config.js重点看publicPath// vue.config.js module.exports { // 部署在域名根目录可以保持默认 / publicPath: /, // 部署到子路径例如 https://example.com/admin/ // publicPath: /admin/, // 如果只能使用相对路径也可以写成 ./ // 但不建议在 history 模式下无脑用原因见下文 outputDir: dist, productionSourceMap: false, devServer: { historyApiFallback: true } }这里有个特别容易踩的坑很多教程会让你把publicPath设置成./这个配置在 hash 模式下通常没问题但在 history 模式下你访问https://example.com/user/list时浏览器解析相对路径./assets/index.js时会把它解析成https://example.com/user/assets/index.js而不是https://example.com/assets/index.js于是资源 404页面直接白屏。所以我的建议是部署在根目录就用/部署在子目录就用绝对路径/子目录/尽量不要依赖相对路径来解决部署问题。4.3 第三步配置 Nginx 回退如果部署在 Nginx 上确保存在下面这类配置server { listen 80; server_name example.com; root /var/www/project/dist; index index.html; location / { try_files $uri $uri/ /index.html; } }try_files $uri $uri/ /index.html的意思是先尝试把请求作为真实文件返回再尝试作为目录返回两者都找不到时返回index.html。这样就保证了 history 模式下刷新子路由不会出现 404。4.4 第四步重试懒加载 chunk 404有时候主页面能打开但点击某个页面时报 chunk 加载失败。除了检查publicPath外还可以在全局给动态 import 加一个“加载失败后强制刷新”的兜底。这个方案要谨慎使用但确实能缓解一些偶发问题// 路由懒加载标准写法加一个 catch 重试 const UserList () import(/views/UserList.vue) // 如果希望加载失败后提示或重试可以自行封装一个 lazyLoad 函数 function lazyLoad(view) { return () import(/views/${view}.vue).catch((error) { console.error(chunk 加载失败尝试刷新页面, error) window.location.reload() return Promise.reject(error) }) }这只是兜底核心还是要把publicPath和服务器回退配置正确。4.5 验证方式改完配置后重新执行vue-cli-service build # 或者 npm run build然后把dist目录里的index.html打开看一眼资源引用路径是否正确。部署后用一个带路径的 URL比如https://example.com/user/list刷新测试确认主文档返回 200且资源路径能找到。5. vite build 场景的修复方法base 配置与服务器适配用 Vite 构建的项目原理和 vue-cli 基本一样但配置项和部分行为有区别不能直接拿 vue.config.js 的思路硬套。5.1 配置 vite.config.js 的 base// vite.config.js import { defineConfig } from vite import vue from vitejs/plugin-vue export default defineConfig({ // 部署在根目录 base: /, // 部署在子路径比如 https://example.com/admin/ // base: /admin/, // 也可以使用相对路径但同上history 模式下要小心 // base: ./, plugins: [vue()] })Vite 的base会影响index.html中静态资源的引用前缀动态import()生成的 chunk 路径import.meta.env.BASE_URL的值这个值如果被用到路由createWebHistory(import.meta.env.BASE_URL)里也会间接影响路由基础路径。所以如果项目里路由写成const router createRouter({ history: createWebHistory(import.meta.env.BASE_URL), routes })那么base配置本身就同时控制了路由的基础路径必须和部署路径一致否则深层路由刷新依旧会有问题。5.2 构建后检查 Vite 产物资源路径Vite 构建完成后建议用命令确认npm run build grep -Eo (src|href)[^]* dist/index.html如果看到href/assets/index-Dx2G5B.js说明资源前缀是根路径如果看到href/admin/assets/index-xxx.js说明子路径前缀生效。把这个结果和实际部署路径对比一下就能判断base是否配置正确。5.3 Vite 项目中特殊的资源引用问题Vite 项目中如果代码里这样写const imgUrl new URL(./img/logo.png, import.meta.url).href构建时这个资源的路径也会受base影响。如果base配错这些图片资源同样会 404。排查白屏问题的时候别只盯着 JS/CSS也可能有图片或字体资源 404只不过 JS/CSS 挂了影响最大。5.4 开发环境与生产环境的差异提醒vite dev开发时跑在内存里默认行为是根目录/你很难察觉到base的错误。很多项目就是开发环境一切正常生产构建部署后才暴露。所以没有条件在本地起 Nginx 的同学至少要在部署后用真实域名做一次深度路由的刷新测试。6. 服务器端通用配置Nginx、平台托管与子路径部署的处理前端配置只是修复工作的一半另一半在服务器。这里把主流部署方式一次性讲清楚。6.1 一份可以抄的 Nginx 模板推荐的生产环境配置模板server { listen 80; server_name example.com; root /var/www/project/dist; index index.html; location / { try_files $uri $uri/ /index.html; } # 带 hash 的静态资源可以开长缓存提升访问速度 location /assets/ { expires 30d; add_header Cache-Control public, immutable; } # index.html 不建议长缓存否则发版后用户会拿到旧的 html location /index.html { add_header Cache-Control no-cache, no-store, must-revalidate; } }注释里已经写清楚了我再额外强调两句入口index.html如果被浏览器长缓存下次部署新版本时浏览器可能还拿着旧index.html里面引用的旧 hash 文件已经被服务器清理了就会出现“部署后部分用户白屏或 chunk 404”。静态资源可以强缓存入口文件不要。6.2 子路径部署的特殊处理假设应用部署在https://example.com/admin/Nginx 配置要做对应调整server { listen 80; server_name example.com; location /admin/ { alias /var/www/project/dist/; try_files $uri $uri/ /admin/index.html; } }同时前端base或publicPath必须配置成/admin/。这里最容易出问题的是你配了try_files $uri $uri/ /index.html但你的应用实际在/admin/下回退到/index.html会把资源路径全部打回根路径依旧白屏。记得回退路径也要带上子路径。6.3 其他服务器和静态托管平台Node 服务Express使用app.get(*, (req, res) res.sendFile(indexPath))做回退。IIS需要安装 URL Rewrite 模块写一个 inbound rule把所有非文件请求重写到index.html。常见的静态托管平台后台一般有“SPA / Rewrites”设置将/*重写到/index.html即可。无论什么平台核心思想都一样让非静态资源的请求都落到前端入口页面。7. 容易被忽略的隐蔽坑多级路由、动态 import 与缓存前面讲的是主流问题但实际线上还会遇到一些更隐蔽的坑尤其是项目规模上来之后。我把这几年碰到过的典型案例写在下面。7.1 嵌套路由刷新后 404有的项目路由结构特别深比如/user/profile/settings。如果服务器回退规则正确通常不会 404。但如果你采用的方案是把publicPath设为./那么访问这个三层路径时浏览器看到相对路径./assets/index.js会把它解析成/user/profile/settings/assets/index.js结果必然 404。这也是为什么我在前面反复强调相对路径./不是 deploy 的银弹history 模式下更容易翻车。解决方法是改用带完整部署上下文的前缀比如/assets/或/子目录/assets/。7.2 动态 import 的 chunk 加载失败SPA 项目里大量使用路由懒加载比如const routes [ { path: /order, component: () import(/views/Order.vue) } ]这些组件会被打包成独立 chunk并在运行时动态加载。如果你的base/publicPath和实际部署路径不一致主包可能侥幸加载成功但每次动态请求 chunk 时都会 404。表现就是首页能开点“订单”就白屏或弹 404。如果只想应急可以给 chunk 加载失败加一个全局提示或重试逻辑。但根本解法还是把资源路径配好并确保服务器返回index.html。7.3 发版后白屏的缓存问题有一个很典型的场景前端发版后部分用户仍然白屏但清除浏览器缓存后又正常。原因通常是浏览器缓存了旧的index.html它引用的 JS 文件名字是旧的 hash而服务器上的旧文件已被新版本覆盖或清理。处理方式就是前面提到的对index.html设置no-cache或协商缓存对带 hash 的资源设置长缓存。这样用户每次访问时至少能拿到最新的 HTML 入口再由 HTML 引向新版本的资源文件。7.4 自动部署工具上传文件不完整这个坑和纯粹的前端配置无关但更容易让人误判。有一些部署脚本用 FTP 或对象存储同步一边传输一边用户访问可能访问到“新 HTML 旧资源”的混合状态。如果是自动部署建议先上传静态资源最后再覆盖index.html尽量避免部署过程中出现资源切割的状态。8. 如何从源头避免构建配置草案与部署前的自检清单问题修完不是终点。我在团队里推行了一套部署前自检流程把这套流程固化下来可以有效减少同类问题反复发生。8.1 项目启动时就定下的几个问题开始一个新项目或决定接入 history 路由前先问自己三个问题项目最终部署的域名路径是什么根路径还是子路径谁负责服务器配置我能不能控制服务器的回退规则如果部署环境完全不可控是否考虑用 hash 模式如果答案为“不能控制服务器”那建议直接选 hash 模式省得后面一堆麻烦。8.2 build 前的四项配置检查我在每次执行build之前都会确认四个点检查项关键配置说明路由模式history / hashhistory 必须配服务器回退构建资源前缀publicPath/base必须与部署路径一致服务器回退try_files/ 平台 rewrite非静态资源请求返回入口 HTML入口缓存策略index.html不设长缓存防止发版后拿旧壳加载旧资源8.3 部署后的验证命令部署完成后我一般会快速跑两条命令确认# 1. 确认入口资源路径 grep -Eo (src|href)[^]* dist/index.html # 2. 确认深层路由会回退到 index.html curl -i https://your-domain.com/user/profile如果第二条命令返回的Content-Type是text/html状态码不是 404说明回退生效。然后再到浏览器无痕窗口里直接访问一个深层路由并刷新确认页面渲染正常。8.4 给团队的小规范如果你们团队不只一个人维护前端部署可以把下面几条写进项目 README新增子路径部署需求时必须同步改publicPath/base和服务器配置只改一边不生效所有项目默认使用带 hash 的资源文件名构建工具默认行为不要手动去掉线上问题先抓“主文档状态码 资源请求路径”再讨论配置变更避免瞎猜。我在实际处理中发现这类“刷新 404 / 白屏”问题本质上都是同一个三角关系出错路由模式、资源前缀、服务器回退只要有一个不匹配线上就会出问题。你按顺序检查先看主文档是不是 404再看资源请求路径前缀对不对最后确认服务器有没有把未知路径回退到入口 HTML九成都能解决。修完之后也别急着走顺手把入口 HTML 的缓存策略检查一遍不然下次发版还会遇到另一个“刷新后白屏”。