一个内部管理后台,本地开发时改一行样式,浏览器五十毫秒内就更新了,快得让人以为项目很轻。到了上线,首页转圈八秒,运营在群里问是不是服务器挂了。把构建产物打开一看,一个 index-6f2a.js 有 3.8MB,图表库、日期库、整个组件库全在里面,首屏根本用不上。

更常见的是另一种:本地怎么点都正常,部署到测试环境直接白屏,控制台一行 404,请求的是 /assets/index-xxxx.js,而文件实际在 /admin/assets/。代码没坏,是构建时的公共路径配错了。

这篇讲什么:Vite 开发服务器为什么快,生产环境为什么还要再打包一次,构建产物里的哈希和分包是怎么回事,base 路径和缓存头怎么影响上线。读完你能做到:看懂一次 vite build 的输出;把首屏体积拆下来;遇到「本地正常、线上白屏」先查路径和产物,而不是怀疑代码。

版本说明:本文按 Vite 8 写。Vite 8(2026 年 3 月发布)把开发和生产统一到 Rolldown 这一个打包器上,配置项和插件接口基本沿用此前的写法。如果你还在 Vite 5 或 6,第五节的拆包配置仍然通用,差异主要在构建速度和默认浏览器目标。

开发为什么快:它根本没打包整个项目

传统打包器的工作方式是「先构建,再启动」:把所有入口、依赖、样式读一遍,生成一个或多个包,然后开发服务器才可用。项目大了,冷启动一分钟很正常,改一行代码还要重新算一遍依赖图。

Vite 换了个顺序:开发服务器先启动,浏览器要什么文件,它当场转换什么文件。入口 HTML 里那行 <script type="module" src="/src/main.ts"> 原样发给浏览器,浏览器按 ES 模块规则去请求 main.ts,Vite 收到请求再编译这一个文件,把它里面的 import 改写成浏览器能访问的 URL。

开发时的一次页面加载
浏览器请求入口拿到 HTML 和入口模块地址
Vite 按需转换只编译当前请求的文件
依赖预构建第三方包提前合成少量 ESM 文件
浏览器执行继续请求它 import 的模块

快的原因有三层。第一,没有全量构建,启动时间跟项目大小基本无关,只跟入口有关。第二,单文件转换很便宜,Vite 8 用 Rust 写的 Rolldown 做依赖预构建和转换,比纯 JS 的打包器快一个量级。第三,热更新只替换改动的模块和它影响的边界,不刷新整页,也不重新构建整张图。

「依赖预构建」值得单独说。第三方包很多是 CommonJS,或者一个包拆成几百个小文件。浏览器原生 ESM 不认识 CommonJS,几百个请求也吃不消。Vite 在第一次启动时把这些依赖合成少量 ESM 文件,缓存在 node_modules/.vite,之后直接复用。新增依赖时它可能重新构建并刷新页面,这不是出错,是预构建缓存失效。

开发服务器的快,是「把工作推迟到请求发生时」。这不代表页面运行时也快。首屏要下载多少 JS、执行多久,仍然取决于你的代码和依赖,跟开发服务器多快没有关系。

生产为什么还要打包:五件开发时不需要的事

既然浏览器已经能直接跑 ESM,为什么不能把源码原样传上去?可以,但代价很大。生产构建主要做五件事:

做的事不做的后果
合并请求几百个模块就是几百次请求,每个都有连接和头部开销,弱网下排队明显
压缩与去掉死代码体积可能是打包后的三到五倍,没被用到的导出也一起下载
语法降级新语法在旧浏览器直接报错,团队得按最老的用户环境写代码
代码拆分首屏被迫加载全部路由和全部重型依赖
文件名带哈希没法给静态资源设长期缓存,每次发版用户都得重新下载

还有一件容易被忽略的事:生产构建会把 import.meta.env、define 里的常量替换成字面量,把 process.env.NODE_ENV 换成 "production",从而让很多库的调试代码被摇掉。开发时这些分支还在,生产时没了,行为可能有细微差别。

所以「开发能跑」和「构建能跑」是两件事,「构建能跑」和「部署能跑」又是两件事。每次上线前,至少要用构建产物起一次静态服务,把主流程点一遍。

配置里真正影响上线的几项

Vite 的配置项很多,日常改来改去的大部分不影响线上。下面这五项会直接影响产物和部署,值得先弄明白:

// vite.config.js
import { defineConfig } from "vite";
import { fileURLToPath, URL } from "node:url";

export default defineConfig({
  base: "/admin/",
  resolve: {
    alias: {
      "@": fileURLToPath(new URL("./src", import.meta.url))
    }
  },
  define: {
    __APP_VERSION__: JSON.stringify("1.4.0")
  },
  build: {
    target: "baseline-widely-available",
    sourcemap: "hidden",
    outDir: "dist"
  }
});

base 决定产物里的资源 URL 前缀。部署在域名根目录,用 /;部署在 https://example.com/admin/,必须写 /admin/。前端路由的 base 也要跟着改,否则页面能打开,跳转全 404。用相对路径 ./ 可以省掉这层配置,但只在「HTML 和资源同目录、没有前端路由」时可靠,后台项目别图省事。

alias 是 import 的别名,能少写一长串相对路径。要注意它只在打包器里生效,TypeScript 的类型检查不认,得在 tsconfig.json 的 paths 里再写一遍。两边不同步时,编辑器报红线但构建通过,或者反过来。

define 是编译期文本替换。字符串必须用 JSON.stringify 包起来,否则替换进去的是裸文本,运行时变成未定义变量。它适合放版本号、构建时间这类常量;不要拿它塞运行时才确定的配置。

build.target 决定语法降级到哪一代浏览器。Vite 8 的默认目标已经抬到 Baseline Widely Available(大致是 Chrome 111、Safari 16.4 这一代,2026 年初的标准)。如果业务还要支持更老的设备,得显式写低,并接受更大的产物和更慢的构建。

sourcemap 决定是否生成映射文件。线上排查错误离不开它,但公开的 map 等于把源码送出去。"hidden" 会生成文件但不在 JS 末尾写注释,配合服务端限制访问,是比较常见的折中。

分包:不是拆得越细越好

首屏体积大,第一反应是「拆包」。拆包分两种,目的完全不同。

第一种是按路由或功能动态导入。用户不进那个页面,就不下载那份代码:

// 路由级懒加载
const routes = [
  { path: "/", component: () => import("./pages/home.js") },
  { path: "/orders", component: () => import("./pages/orders.js") }
];

// 重型组件按交互加载
button.addEventListener("click", async () => {
  const { openChart } = await import("./chart.js");
  openChart(data);
});

第二种是把不常变的第三方依赖单独抽成 vendor chunk,利用浏览器缓存:业务代码每周发版都变,React、图表库几个月才升级一次。放在同一个包里,每次发版用户都得重下全部;拆开后,vendor 的哈希不变,用户只下业务那部分。

build: {
  rollupOptions: {
    output: {
      manualChunks(id) {
        if (!id.includes("node_modules")) return;
        if (id.includes("echarts")) return "charts";
        if (id.includes("react")) return "react";
        return "vendor";
      }
    }
  }
}

但拆包有反作用。拆成十几个 20KB 的小块,浏览器要发十几个请求,还要等依赖链一层层解析,首屏反而更慢。判断标准是:这个块是否只在特定路由用、体积是否值得单独缓存、它和主包是否几乎同时需要。三个都不满足,就别拆。

不要把「首屏必需」的库塞进异步 chunk。比如登录页要用的请求库、UI 框架,拆出去只会多一次往返。拆包的收益来自「不需要时不下载」,不是来自「块数多」。

产物路径、缓存和部署

vite build 之后,dist 里通常是这样的结构:

dist/
  index.html
  assets/
    index-a1b2c3d4.js
    vendor-9f8e7d6c.js
    index-5b4c3d2e.css

文件名里的哈希是根据内容算的:内容不变,哈希不变;内容一变,哈希就变。这让你可以给 assets/ 设一年缓存,而 index.html 必须每次回源,否则用户会一直拿着旧页面去请求已经被删掉的旧 JS。

# nginx.conf 片段
location /assets/ {
  add_header Cache-Control "public, max-age=31536000, immutable";
}

location = /index.html {
  add_header Cache-Control "no-cache";
}

no-cache 不是不缓存,而是每次使用前都要向服务器确认。对 HTML 来说,这个开销可以接受,换来的是发版即时生效。

发版时还有一个经典事故:用户开着旧页面,你部署了新版本,旧哈希的文件被删了。用户点一个懒加载路由,浏览器去请求 orders-旧哈希.js,得到 404,页面卡住或白屏。修法有三层:HTML 不缓存,减少旧页面的存活时间;部署时保留上一两个版本的静态资源;动态导入失败时给用户一个「刷新页面」的提示,而不是静默失败。

完整场景走查:一个后台从 3.8MB 到 420KB

需求是一个运营后台:首页是数据概览,有图表;订单页有表格和导出;设置页很少用。第一版所有页面写在一个入口里,图表库、日期库、组件库全量引入。构建输出一行警告:

(!) Some chunks are larger than 500 kB after minification.

上线后首屏 JS 3.8MB,4G 网络下八秒才可交互。按下面的顺序处理,每一步都能单独验证。

第一步,先量清楚。把构建输出按 gzip 后的体积排序,再配合包分析工具看大头是谁。这个项目里图表库 1.4MB、日期库 600KB、组件库 900KB。不做这一步,很容易凭感觉去优化一个只有 30KB 的模块。

第二步,处理「全量引入」。日期库改成按需导入加 tree-shaking,体积从 600KB 降到 40KB。注意库的 sideEffects 字段和导入写法,import { format } from "date-fns" 能摇,import dateFns from "date-fns" 往往不能。

第三步,把图表改成按需加载。概览页的图表在首屏下方,用户滚到才需要;订单页的导出组件更是低频。改成动态导入后,首屏少 1.4MB,代价是第一次点「查看图表」会多等三百毫秒,加个骨架屏就过去了。

第四步,拆 vendor。React 和组件库单独成块,业务代码一个块。发版时业务块的哈希变、vendor 不变,回访用户只下载几十 KB。这里踩了一个坑:一开始按每个库拆,拆出十二个块,首屏请求数从 3 个变成 14 个,反而慢了一百多毫秒。最后合成两个块才稳定。

第五步,配 base。这个后台部署在 /admin/ 下。第一版没改 base,本地开发服务器在根路径,正常;预发环境访问 /admin/,HTML 能打开,所有资源 404。改完 base,前端路由的 base 也要同步,否则首页能进、点菜单就跳丢。

第六步,缓存头。给 /assets/ 设一年 immutable,index.html 设 no-cache。发版后测了一遍:新用户直接拿新页面;老用户刷新拿到新 HTML;开着旧页面的用户点懒加载路由,因为旧资源还保留了一个版本,没有 404。

最终首屏 JS 从 3.8MB 降到 420KB,gzip 后约 130KB,4G 下可交互时间从八秒降到两秒出头。这里没有魔法,就是把「首屏不需要的东西」从首屏拿掉,把「不常变的东西」单独缓存。

错误现象对照

构建和部署阶段的问题,现象常常指向错误的方向。先按这张表定位,再去改配置。

现象真实原因第一步查什么
本地正常,部署后白屏,资源 404base 与实际部署路径不一致看 HTML 里的资源 URL 前缀,和 Network 里的实际请求路径
process is not defined某个依赖假设运行在 Node 环境按报错栈找到包,确认是否需要在 define 里补常量
只有 CI 报 Failed to resolve import "./Button"Windows 不区分大小写,Linux 区分,文件名大小写不一致核对 import 写法和磁盘上的真实文件名
首屏慢,构建警告 chunk 超过 500KB重型依赖进了首屏,或者没有按需加载看构建输出的体积排行,确认大头是谁
旧标签页报 Failed to fetch dynamically imported module发版删掉了旧哈希文件,旧页面还在请求查 HTML 缓存头,以及部署是否保留旧版本资源
生产样式丢失或顺序不对CSS 拆分策略、导入顺序与开发时不同对比构建产物里的 CSS 顺序和开发时的加载顺序
改代码触发了整页刷新,不是热更新改动的模块没有可接受的边界,或导出方式不满足 HMR 条件看终端里 HMR 的提示,确认改动文件是否被某个接受模块引用

边界与代价

Vite 的快,建立在「开发时不打包」上。这带来一个必须接受的代价:开发环境和生产环境的模块加载方式不同,某些问题只在构建后出现。CSS 顺序、动态导入路径、环境变量替换、压缩后的报错行号,都是高发区。团队要把「用构建产物验收」写进流程,不能只看开发服务器。

vite preview 只是本地静态服务器,用来快速看构建结果,不等于生产环境。它不会替你做 gzip、缓存头、反向代理和路径重写。路径类问题最终要在 nginx 或 CDN 环境里验证。

分包不是免费的性能。每多一个块,就多一次请求和一次依赖解析;HTTP/2 能缓解,但缓解不了「首屏必须等它」的串行关系。拆包前先问:这个块是不是首屏必需?它的体积是否值得单独缓存?回答不了,就先不拆。

sourcemap 也有代价。完整的 map 文件可能和产物一样大,构建时间上升,上传监控服务还要考虑脱敏。不开 map,线上报错只剩压缩后的一行列号,排查基本靠猜。折中方案是 hidden map 加访问限制,或者只给错误监控平台上传。

Vite 适合应用和库,但不是所有场景都合适。需要模块联邦、复杂 DLL、极端定制的 webpack 老项目,迁移成本可能大于收益。SSR 场景通常由框架层(比如基于 Vite 的元框架)接管,自己拼要处理服务端入口、资源清单和 hydration,别低估。

小结

开发快是因为按需Vite 不预先打包整个项目,浏览器请求什么就转换什么,依赖预构建负责把第三方包变成少量 ESM。
生产打包是为了传输和缓存合并请求、压缩、摇树、降级、拆包、内容哈希,这六件事开发服务器都不做。
base 和缓存头决定能不能打开部署在子路径必须配 base;HTML 不缓存,带哈希的资源长缓存,旧资源留一个版本。
拆包看收益,不看块数按路由和交互拆,vendor 单独缓存;首屏必需的不要异步,拆得太碎反而更慢。

这几件事今天就能验证:

  1. 跑一次 vite build,用一个普通静态服务器打开 dist,把主流程点一遍,记录和开发环境的差异。
  2. 把 base 改成 /test/,重新构建,观察 HTML 里的资源路径和 404。
  3. 给一个重型组件加动态 import(),在 Network 面板确认点击前没有下载它。
  4. 对比有 manualChunks 和没有时的构建输出,记录 chunk 数量和第二次访问的缓存命中情况。
  5. 部署一次新版本,保持旧标签页打开,点一个懒加载路由,复现旧哈希 404,再补上「刷新提示」。

下一篇讲TypeScript 入门。Vite 在构建时只做类型擦除,不做类型检查:类型写错照样能构建成功,问题留到运行时。这正好接上下一篇要处理的事,类型到底能保证什么,又不能保证什么。