前端-08-构建工具-Vite与Webpack
这篇讲什么
浏览器只认识 HTTP 请求、HTML、CSS 和它自己版本的 JavaScript;而现代前端项目写的是 TypeScript(TS)、JSX、SCSS、
import语法和几百个 npm 包。构建工具(build tool)就是这两者之间的翻译官与物流公司。本篇先讲清「为什么需要它」,再解剖构建工具的内部流水线,然后分别深入 Webpack 与 Vite 两套主流方案,最后给出对比、选型与部署要点。
一、是什么
构建工具是一类把「开发时写的源码」转换成「浏览器能直接运行的产物」的程序。它的输入是源码目录与一份配置,输出是 dist/ 里的静态资源;同时它还会起一个开发服务器(dev server),负责热更新(HMR)与接口代理(proxy)。
常见的构建工具按其核心角色可分成几层:
| 层次 | 代表 | 职责 |
|---|---|---|
| 打包器(bundler) | Webpack、Rollup、Rspack | 从入口出发解析依赖图,把多个模块合成少量文件 |
| 转译器(transpiler) | TypeScript、Babel、SWC | 语法层面的转换(TS → JS、新语法 → 老语法) |
| 压缩器(minifier) | Terser、esbuild、SWC | 删除空白、缩短变量名、删除死代码 |
| 开发服务器 | webpack-dev-server、Vite dev server | 提供本地 HTTP 服务、HMR、代理 |
| 元框架(meta-framework) | Nuxt、Next.js | 在打包器之上再封装路由、SSR、约定式目录 |
一个常见误区
「构建工具」不等于「打包器」。Vite 在开发阶段不做打包(它用浏览器原生 ESM 直接加载模块),只在生产构建时才调用 Rollup 打包。把 Vite 叫成「打包器」在开发语境下是不准确的。
二、为什么需要它
2.1 先看没有构建工具的世界
假设我们要写一个页面,用到一个日期格式化库。最朴素的写法是手写 index.html,用一堆 <script> 标签按顺序加载:
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8" />
<title>手写页面</title>
<!-- 问题 1:必须记住库的 CDN 地址,而不是写 import -->
<script src="https://cdn.example.com/dayjs.min.js"></script>
<!-- 问题 2:必须记住加载顺序,用到了 dayjs 就必须排在它后面 -->
<script src="./js/format.js"></script>
<script src="./js/main.js"></script>
<script src="./js/legacy-plugin.js"></script>
<!-- 问题 3:想用 TS/JSX?浏览器根本不认,得先手动编译一遍 -->
<!-- 问题 4:文件一多,就是 30 个 script 标签、30 个请求 -->
</head>
<body>
<div id="app"></div>
</body>
</html>
这套方案在「一个页面 + 两个脚本」时完全够用,甚至比构建工具更快上线。但项目一旦长大,会依次撞上下面这些墙:
| 问题 | 具体表现 | 构建工具怎么解决 |
|---|---|---|
| 浏览器不认识裸模块名 | import dayjs from "dayjs" 报错,浏览器只会当相对路径或 URL 解析 | 依赖解析(resolve)把 dayjs 映射到 node_modules/dayjs/... |
| 语法需要转换 | TS 类型注解、JSX、可选链、装饰器,旧浏览器直接语法错误 | 转译(transpile):TS/Babel/SWC/esbuild |
| 加载顺序与全局污染 | <script> 靠书写顺序维持依赖,库之间抢全局变量 | 模块化打包,依赖顺序由依赖图保证 |
| 请求数爆炸 | 100 个模块 = 100 次网络往返,HTTP/1.1 下排队严重 | 打包(bundle)合并成少量文件 |
| 体积与性能 | 源码带注释、空白、未使用代码;首屏加载全部逻辑 | 压缩(minify)、Tree Shaking、代码分割(code splitting) |
| 开发体验 | 改一行要手动刷新,甚至手动重新编译 | HMR(热模块替换)与 dev server |
| 资源处理 | 图片、字体、CSS 也要参与依赖和哈希命名 | loader/plugin 把非 JS 资源也纳入流水线 |
| 缓存与发布 | 文件名不变,用户浏览器一直拿旧缓存 | 内容哈希文件名(app.4f3a1c.js) |
2.2 一句话总结动机
核心结论
构建工具存在的根本原因,是开发者的表达方式(模块化、类型、现代语法、组件化)与浏览器的执行约定(无裸模块解析、无转译、请求数敏感、语法版本固定)之间存在鸿沟。构建工具把「人写起来舒服的源码」编译成「浏览器跑起来划算的产物」,同时在开发期提供热更新、代理、Source Map 等支撑。
用一句话抽象:构建过程是一个映射
而开发服务器的目标则是让编辑到看到结果的延迟 尽可能小。
三、构建工具做了什么
不管哪款工具,内部流水线都可以拆成这几个阶段:
① 入口 (entry)
↓
② 依赖解析 (resolve):裸模块名 → 真实文件路径
↓
③ 加载与转换 (load / transform):TS、JSX、CSS、图片 → JS 模块
↓
④ 构建依赖图 (graph):模块 → 模块的引用关系 DAG
↓
⑤ 分块与打包 (chunk / bundle):按规则切分成若干输出文件
↓
⑥ 优化 (optimize):Tree Shaking、压缩、作用域提升、分包
↓
⑦ 生成产物 (emit):带哈希的文件名 + Source Map + HTML 注入
| 阶段 | 做什么 | Webpack 对应概念 | Vite 对应概念 |
|---|---|---|---|
| 入口 | 从哪开始找依赖 | entry | build.rollupOptions.input |
| 解析 | 裸名 → 路径、扩展名补全、别名 | resolve.extensions / alias | 同左(内部用 Rollup 插件) |
| 加载转换 | 把非 JS 内容变成 JS 模块 | module.rules 里的 loader | 内置转换 + 插件 |
| 依赖图 | 记录谁引用谁 | Compilation / ModuleGraph | ModuleGraph |
| 分块 | 拆成多个输出文件 | optimization.splitChunks | build.rollupOptions.output.manualChunks |
| 优化 | 删死代码、压缩 | mode: "production" + Terser | esbuild/Rollup 内置 |
| 产物 | 写文件、注入 HTML | output + HtmlWebpackPlugin | build.outDir + index.html 入口 |
记住这条主线
学任何构建工具,都先问四个问题:入口在哪?谁来转译这类文件?产物叫什么、放哪里?开发服务器怎么工作? 这四问答上来,配置就不是背出来的了。
四、两种打包范式:Bundle 与 Native ESM(Bundleless)
这是理解 Vite 与 Webpack 差异的关键前置知识。
4.1 Bundle(先打包,再交给浏览器)
Webpack 的经典模式:开发服务器启动时,把整个应用打包成 bundle.js 放进内存,浏览器加载这一个文件。
- 优点:浏览器只请求少量文件;对浏览器能力无要求;依赖处理灵活(CommonJS 也能玩)。
- 缺点:启动时间随项目规模近似线性增长(要把所有模块都跑一遍),大项目冷启动动辄 10–60 秒。
4.2 Native ESM / Bundleless(按需编译,浏览器自己拉模块)
Vite 的开发模式:启动服务器几乎不做打包,只做依赖预构建(pre-bundling);浏览器请求 main.ts 时,服务器才把这个模块及其直接导入转译后返回,浏览器再发起下一批请求。
- 优点:冷启动与项目规模基本解耦,只编译当前页面真正用到的模块;HMR 精度高(只失效一条模块链)。
- 缺点:必须假设浏览器支持原生 ES Module(现代浏览器都支持);首屏可能出现较多并发请求(Vite 用预构建 + HTTP 缓存缓解);无法直接兼容 CommonJS 依赖,需要预构建转换。
4.3 对比表
| 维度 | Bundle(Webpack / Rollup 生产构建) | Native ESM / Bundleless(Vite 开发态) |
|---|---|---|
| 启动成本 | ,全量打包 | 近似 ,按需编译 |
| 模块请求数 | 少(合并的大文件) | 多(每个模块一次请求,可被缓存) |
| 浏览器要求 | 低,产物是普通脚本 | 需要原生 ESM 支持 |
| HMR 精度 | 中,边界由 loader/plugin 决定 | 高,模块图精确失效 |
| CommonJS 依赖 | 原生支持 | 需预构建转成 ESM |
| 生产产物 | 就是打包结果 | Vite 生产态仍走 Rollup 打包 |
| 典型痛点 | 大项目冷启动慢 | 首屏请求瀑布、需注意依赖预构建 |
| 适合 | 巨型老项目、需要极细粒度控制 | 新项目、中大型 SPA、组件库开发 |
结论
「Bundleless」并不是说生产环境不打包,而是说开发环境不打包。生产环境仍然要打包,因为压缩、Tree Shaking、长期的 HTTP 缓存收益远大于打包成本。
五、Webpack
Webpack 是使用最广的打包器,核心思想是「一切皆模块」:JS、CSS、图片、字体都可以是模块,用统一的依赖图串起来。
5.1 五个核心概念
| 概念 | 作用 | 一句话理解 |
|---|---|---|
entry | 声明依赖图的起点 | 「从哪个文件开始顺藤摸瓜」 |
output | 声明产物写到哪里、叫什么 | 「结果放哪个目录、文件名模板」 |
loader | 把非 JS/新语法文件转成模块 | 「文件级翻译官」 |
plugin | 在构建生命周期里做额外事情 | 「流程级改造者」 |
mode | 一组内置优化的开关 | development / production / none |
它们的关系可以用一条链表示:
loader 与 plugin 的区别是最常考的面试题:
| 维度 | loader | plugin |
|---|---|---|
| 作用粒度 | 单个文件(模块) | 整个构建过程 |
| 配置位置 | module.rules | plugins 数组 |
| 本质 | 一个转换函数 | 一个带 apply(compiler) 的类 |
| 典型例子 | ts-loader、css-loader、file-loader | HtmlWebpackPlugin、DefinePlugin |
| 常见困惑 | 为什么 loader 从右往左执行 | 为什么 plugin 是 new 出来的 |
loader 的执行顺序
use: ["style-loader", "css-loader"]的执行顺序是从右到左、从下到上:先css-loader把 CSS 变成 JS 模块,再style-loader把它注入<style>。可以记成「配置写在后面的是先干活的」。
5.2 完整配置文件示例
下面这份 webpack.config.js 覆盖了 TS + React + CSS + 资源 + 分包 + 开发服务器的常见需求,逐项注释:
// webpack.config.js —— CommonJS 写法,Webpack 也支持 .mjs / .ts 配置
const path = require("node:path");
const HtmlWebpackPlugin = require("html-webpack-plugin");
const { DefinePlugin } = require("webpack");
const MiniCssExtractPlugin = require("mini-css-extract-plugin");
const CssMinimizerPlugin = require("css-minimizer-webpack-plugin");
const BundleAnalyzerPlugin =
require("webpack-bundle-analyzer").BundleAnalyzerPlugin;
// 通过 --env 传入自定义开关:webpack --env analyze
module.exports = (env = {}) => ({
// 【mode】development 会开启可读的模块名、不做压缩、便于调试;
// production 会开启压缩、Tree Shaking、作用域提升。
mode: env.production ? "production" : "development",
// 【entry】依赖图起点。写成对象可以支持多页应用(MPA)多个入口。
entry: {
main: "./src/main.tsx",
},
// 【output】产物位置与命名。contenthash 让文件内容不变则文件名不变,
// 从而可以给静态资源设置超长缓存(见第八节部署要点)。
output: {
path: path.resolve(__dirname, "dist"),
filename: "assets/js/[name].[contenthash:8].js",
chunkFilename: "assets/js/[name].[contenthash:8].chunk.js",
assetModuleFilename: "assets/media/[name].[hash:8][ext]",
// 每次构建前清空 dist,避免旧哈希文件堆积
clean: true,
// 让部署到子路径(如 CDN 目录)时资源引用仍然正确
publicPath: "/",
},
// 【resolve】模块解析规则
resolve: {
// 导入时可以省略扩展名
extensions: [".tsx", ".ts", ".jsx", ".js", ".json"],
// 路径别名,避免 ../../../
alias: {
"@": path.resolve(__dirname, "src"),
},
},
// 【module.rules】loader 配置:把非 JS 资源变成模块
module: {
rules: [
{
test: /\.tsx?$/,
// 排除 node_modules,否则构建会慢到无法忍受
exclude: /node_modules/,
use: {
loader: "ts-loader",
options: {
// 让类型检查交给编辑器/CI,构建走 transpileOnly 提速
transpileOnly: true,
},
},
},
{
test: /\.css$/,
// 顺序很重要:先 css-loader 解析 @import/url,再决定注入还是抽离
use: [
env.production ? MiniCssExtractPlugin.loader : "style-loader",
"css-loader",
],
},
{
test: /\.(png|jpe?g|gif|svg)$/i,
// Webpack 5 内置资源模块,不再需要 file-loader / url-loader
type: "asset",
parser: { dataUrlCondition: { maxSize: 8 * 1024 } }, // 小于 8KB 内联为 base64
},
{
test: /\.(woff2?|ttf|eot)$/i,
type: "asset/resource",
},
],
},
// 【plugins】生命周期级别的扩展
plugins: [
// 以模板生成 index.html,并自动注入所有产出的 script/link 标签
new HtmlWebpackPlugin({
template: "./public/index.html",
minify: env.production,
}),
// 把编译期常量注入源码:源码里写 process.env.NODE_ENV 会被直接替换
new DefinePlugin({
"process.env.NODE_ENV": JSON.stringify(
env.production ? "production" : "development"
),
}),
// 生产环境把 CSS 抽成独立文件,便于并行加载与缓存
...(env.production ? [new MiniCssExtractPlugin({ filename: "assets/css/[name].[contenthash:8].css" })] : []),
// 按需启动体积分析:webpack --env analyze
...(env.analyze ? [new BundleAnalyzerPlugin()] : []),
],
// 【optimization】产物优化
optimization: {
// 生产环境压缩:JS 用 Terser,CSS 用 css-minimizer
minimize: env.production,
minimizer: ["...", new CssMinimizerPlugin()],
// 把模块 id 稳定下来,避免「只改一行代码,所有 chunk 哈希全变」
moduleIds: "deterministic",
// 【代码分割】把第三方依赖、公共模块拆成独立 chunk
splitChunks: {
chunks: "all",
cacheGroups: {
// React 这类几乎不变的库单独打包,长期命中浏览器缓存
vendor: {
test: /[\\/]node_modules[\\/]/,
name: "vendors",
priority: -10,
},
},
},
// 把运行时代码单独抽出,避免修改业务代码导致 vendor 哈希变化
runtimeChunk: "single",
},
// 【devServer】webpack-dev-server 配置
devServer: {
port: 5173,
open: true,
hot: true, // 开启 HMR
historyApiFallback: true, // SPA 路由回退:任何 404 都返回 index.html
client: { overlay: { errors: true, warnings: false } },
proxy: [
{
// 开发期把 /api 转发到后端,规避浏览器同源策略
context: ["/api"],
target: "http://localhost:8080",
changeOrigin: true,
pathRewrite: { "^/api": "" },
},
],
},
// 【devtool】Source Map 策略:开发要快且准,生产要独立文件不泄露源码
devtool: env.production ? "source-map" : "eval-cheap-module-source-map",
// 打包体积统计,快速定位意外引入的大依赖
performance: {
hints: env.production ? "warning" : false,
maxAssetSize: 512 * 1024,
},
});
最小可运行配置(如果上面太长,先理解这 15 行):
// webpack.config.js(最小版)
const path = require("node:path");
const HtmlWebpackPlugin = require("html-webpack-plugin");
module.exports = {
mode: "development",
entry: "./src/index.js",
output: { path: path.resolve(__dirname, "dist"), filename: "main.js", clean: true },
module: { rules: [{ test: /\.css$/, use: ["style-loader", "css-loader"] }] },
plugins: [new HtmlWebpackPlugin({ template: "./public/index.html" })],
devServer: { hot: true, port: 5173 },
};
5.3 常用 loader 与 plugin
| 名称 | 类型 | 用途 |
|---|---|---|
ts-loader / babel-loader / swc-loader | loader | TS / 新语法转译 |
css-loader | loader | 解析 CSS 的 @import 与 url() |
style-loader | loader | 把 CSS 以 <style> 注入 DOM |
postcss-loader | loader | 接 Autoprefixer、Tailwind 等 PostCSS 插件 |
sass-loader / less-loader | loader | SCSS / Less 编译 |
asset / asset/resource(内置) | 内置模块类型 | 图片、字体等静态资源 |
HtmlWebpackPlugin | plugin | 生成 HTML 并注入产物引用 |
MiniCssExtractPlugin | plugin | 生产环境抽离独立 CSS 文件 |
DefinePlugin(内置) | plugin | 注入编译期常量 |
CopyWebpackPlugin | plugin | 原样拷贝静态文件 |
BundleAnalyzerPlugin | plugin | 可视化产物体积构成 |
ForkTsCheckerWebpackPlugin | plugin | 独立进程做 TS 类型检查,不阻塞构建 |
实践建议
Webpack 5 起优先用内置的
asset模块类型,不要再装file-loader/url-loader;优先用 SWC 或 esbuild 做纯转译,把类型检查交给tsc --noEmit或ForkTsCheckerWebpackPlugin。
5.4 webpack-dev-server 与 HMR 原理
开发服务器做三件事:提供静态文件服务、处理 SPA 回退与接口代理、通过 WebSocket 推送编译事件。
HMR(Hot Module Replacement,热模块替换)的流程:
① 你保存了 Button.tsx
② Webpack 监听到文件变化,只重新编译受影响的模块(增量构建)
③ 通过 WebSocket 向浏览器发送 hash + ok 消息
④ 浏览器端 hot runtime 用 JSONP/AJAX 拉取更新的 chunk
⑤ 从更新模块向上查找「接受更新」的边界(module.hot.accept)
⑥ 卸载旧模块、执行新模块,页面不刷新,组件状态保留
关键点:
- HMR 的边界由 loader/plugin 决定。React 靠
react-refresh、Vue 靠官方 loader/plugin 提供边界;纯 JS 模块若没有module.hot.accept,Webpack 会回退为整页刷新。 - HMR 只影响开发体验,与生产产物无关。生产环境不会包含 HMR 运行时代码。
- 常见坑:
output.publicPath配置错误会导致 HMR 拉取 chunk 404,表现为「改了没反应」。
5.5 optimization.splitChunks 与 Tree Shaking
代码分割(code splitting)解决「所有代码打成一个巨型文件、首屏全量下载」的问题。三类切分方式:
| 方式 | 做法 | 场景 |
|---|---|---|
| 入口分割 | 多 entry | 多页应用(MPA) |
| 动态导入 | import("./Chart") | 路由懒加载、按需加载大组件 |
| 公共抽取 | splitChunks | 第三方库、被多页共享的代码 |
splitChunks 的几个关键参数:
| 参数 | 含义 | 默认 |
|---|---|---|
chunks | 对哪些 chunk 生效(initial / async / all) | async |
minSize | 小于该体积就不拆 | 20000 字节 |
cacheGroups | 分组规则,可按 test/priority 决定归属 | 内置 defaultVendors、default |
maxInitialRequests | 首屏并行请求上限 | 30 |
分包不是越细越好
拆得过细会产生大量小 chunk,HTTP 请求数与解压开销上升;拆得过粗则缓存粒度变差。经验做法是「变化频率相近的放一起」:框架运行时一个 chunk、大型第三方库各自一个 chunk、业务代码一个 chunk。
Tree Shaking(摇树优化)指删除「被导出但没人引用」的死代码。它有三个前提,缺一不可:
- 必须使用 ES Module(ESM)语法。
import/export是静态结构,打包器能分析出谁用了谁;CommonJS 的require是运行时求值,无法可靠静态分析。 sideEffects声明要正确。在package.json里写:
```json
{ "sideEffects": false }
```
表示「这个包的所有文件都没有副作用,没用到的可以放心删」。若包里有全局注册、polyfill 等副作用文件,必须列出来:
```json
{ "sideEffects": ["*.css", "./src/polyfill.ts"] }
```
mode: "production"(或手动开启optimization.usedExports+minimize)。开发模式为了保留调试信息默认不摇树。
// 只有在 sideEffects 正确时,没被用到的 sum 才会被删除
// utils.js
export const sum = (a, b) => a + b;
export const unused = () => console.log("never called");
// main.js
import { sum } from "./utils";
console.log(sum(1, 2));
三条 Tree Shaking 失效的高频原因
1. 依赖是 CommonJS 的(如老版本 lodash),整包都会被打进去。
2. 写成
import _ from "lodash"再_.debounce,即使库是 ESM 也无法删掉未用函数——应写import debounce from "lodash/debounce"。3. 包内
package.json缺sideEffects: false,打包器保守地保留全部文件。
六、Vite
Vite(法语「快」,读作 /vit/)由 Vue 作者尤雨溪发起,设计目标是把开发体验从「等打包」拉回到「改完立即可见」。
6.1 为什么快
Vite 的速度来自两个方向的分工:
| 阶段 | 做法 | 收益 |
|---|---|---|
| 开发(dev) | 不做全量打包,浏览器通过原生 ESM 按需请求模块,服务器按需编译该模块 | 冷启动与项目规模解耦,秒级启动 |
| 开发(依赖) | 用 esbuild 预构建 node_modules 依赖,把 CommonJS 转成 ESM、把散碎文件合并成一个 | 避免「几百个请求」,且 esbuild 是 Go 写的,比 JS 实现快一到两个数量级 |
| 生产(build) | 调用 Rollup 打包 | 产物成熟、生态与插件完善、Tree Shaking 好 |
| HMR | 基于 ESM 的模块图精确失效,只重新编译被改模块及其边界 | HMR 与项目规模解耦 |
开发态:
浏览器 GET /src/main.ts
→ 服务器即时转译该模块(esbuild)→ 返回 ESM
→ 浏览器解析 import "./App.vue" → GET /src/App.vue → …按需展开
生产态:
vite build → Rollup 解析完整依赖图 → 压缩/分包/哈希 → dist/
关于 esbuild 预构建
依赖预构建结果缓存在
node_modules/.vite。当依赖变化或配置变化时会自动重新构建;可用vite --force或optimizeDeps.force强制刷新。这一层是 Vite「既快又能兼容 CommonJS 包」的关键。
6.2 vite.config.ts 关键配置
// vite.config.ts —— 需要 Node 类型提示时安装 @types/node
import { defineConfig, loadEnv } from "vite";
import vue from "@vitejs/plugin-vue";
import react from "@vitejs/plugin-react";
import { fileURLToPath, URL } from "node:url";
import { visualizer } from "rollup-plugin-visualizer";
// 用函数式配置,才能按 mode 读取环境变量
export default defineConfig(({ mode, command }) => {
const env = loadEnv(mode, process.cwd(), "VITE_");
const isBuild = command === "build";
return {
// 【plugins】Vite 的核心扩展点:一个插件就是一个 Rollup 插件 + 若干 Vite 钩子
plugins: [
vue(), // 或 react():提供框架编译与 HMR 边界
// 按需启动产物体积分析:ANALYZE=1 vite build
...(process.env.ANALYZE
? [visualizer({ open: true, gzipSize: true, filename: "stats.html" })]
: []),
],
// 【base】部署路径。部署到子目录或 CDN 时必须改,否则资源 404
base: env.VITE_BASE ?? "/",
// 【resolve.alias】路径别名,需与 tsconfig 的 paths 保持一致
resolve: {
alias: {
"@": fileURLToPath(new URL("./src", import.meta.url)),
},
},
// 【define】注入编译期常量。注意:会被直接文本替换,不要放敏感信息
define: {
__APP_VERSION__: JSON.stringify(process.env.npm_package_version),
},
// 【css】CSS 预处理与模块化
css: {
preprocessorOptions: {
scss: { additionalData: `@use "@/styles/variables.scss" as *;` },
},
devSourcemap: true,
},
// 【server】仅开发期生效
server: {
port: 5173,
open: true,
host: true, // 允许局域网访问(手机调试)
// 开发期代理,解决前后端分离时的浏览器跨域限制
proxy: {
"/api": {
target: "http://localhost:8080",
changeOrigin: true,
rewrite: (p) => p.replace(/^\/api/, ""),
},
},
},
// 【preview】预览生产产物:vite preview
preview: { port: 4173 },
// 【build】生产构建
build: {
outDir: "dist",
assetsDir: "assets",
sourcemap: isBuild ? "hidden" : false, // 生成但不引用,便于线上排查
target: "es2020", // 控制降级目标,视兼容需求调整
chunkSizeWarningLimit: 800, // 单位 KB,超过就警告
assetsInlineLimit: 4096, // 小于 4KB 的资源内联 base64
// 【Rollup 透传配置】细粒度控制输出
rollupOptions: {
output: {
// 手动分包:把体积大且稳定的依赖单独抽出
manualChunks: {
"vendor-vue": ["vue", "vue-router", "pinia"],
"vendor-utils": ["axios", "dayjs"],
},
// 产物文件名模板
chunkFileNames: "assets/js/[name]-[hash].js",
entryFileNames: "assets/js/[name]-[hash].js",
assetFileNames: "assets/[ext]/[name]-[hash][extname]",
},
},
// 用 esbuild 做压缩(默认),也可换 terser 以换取更小体积
minify: "esbuild",
},
// 【optimizeDeps】依赖预构建控制;遇到「预构建没识别到」的包时手动 include
optimizeDeps: {
include: ["dayjs/plugin/customParseFormat"],
exclude: ["your-local-linked-package"],
},
};
});
6.3 环境变量与 .env
Vite 使用 dotenv 风格的环境文件,只有 VITE_ 前缀的变量才会暴露给客户端代码——这是防止密钥泄漏的设计。
| 文件 | 何时加载 | 说明 |
|---|---|---|
.env | 所有情况 | 公共变量 |
.env.local | 所有情况 | 本地覆盖,应加入 .gitignore |
.env.development | vite dev | 开发专用 |
.env.production | vite build | 生产专用 |
.env.[mode].local | 指定 mode | 优先级最高 |
# .env.development
VITE_API_BASE=/api
VITE_APP_TITLE=我的应用(开发)
# 注意:不加 VITE_ 前缀的变量不会进入客户端代码
DB_PASSWORD=secret # 只对配置函数内的 Node 代码可见
// src/env.ts —— 给 import.meta.env 补类型,获得自动补全
/// <reference types="vite/client" />
interface ImportMetaEnv {
readonly VITE_API_BASE: string;
readonly VITE_APP_TITLE: string;
readonly MODE: string;
readonly DEV: boolean;
readonly PROD: boolean;
}
interface ImportMeta {
readonly env: ImportMetaEnv;
}
// 业务代码里使用
const base = import.meta.env.VITE_API_BASE; // 替换 node 环境下的 process.env
if (import.meta.env.DEV) console.log("仅开发环境执行");
环境变量的两个坑
1.
import.meta.env是构建期静态替换,不是运行时读取。改.env后必须重启 dev server 才生效。2. 不要把密钥写进
VITE_变量。任何进入客户端产物的字符串,用户都能在浏览器里看到——密钥必须留在后端。
6.4 public 目录与资源引用
Vite 项目里有两种资源,规则完全不同:
| 方式 | 位置 | 引用写法 | 是否参与构建 | 适用 |
|---|---|---|---|---|
| 静态直出 | public/ | /logo.png(绝对路径) | 否,原样拷贝到 dist 根 | favicon、robots.txt、第三方校验文件 |
| 模块资源 | src/assets/ | import url from "./logo.png" 或 new URL("./logo.png", import.meta.url) | 是,可哈希、可内联、可 Tree Shaking | 组件里用到的图片、字体、CSS |
// 正确:走构建,得到带哈希的 URL,长缓存友好
import logoUrl from "@/assets/logo.svg";
const img = document.createElement("img");
img.src = logoUrl;
// 正确:动态拼接场景(不会被静态分析成变量时使用)
const url = new URL(`./icons/${name}.svg`, import.meta.url).href;
// 错误:public 里的文件不能这样"模块化引用",路径也不会被哈希
// import logo from "/public/logo.svg"; // ❌
public的四个注意点1.
public里的文件不能用import引入,只能靠 URL 直接访问。2. 引用时不要写
/public/前缀,应该写/logo.png。3. 这些文件不会被哈希,浏览器缓存策略要自己考虑。
4. 生产构建时
public内容被复制到dist根目录,可能覆盖同名产物。
6.5 base 路径与 server.proxy
base 决定产物中所有资源 URL 的前缀,等价于 Webpack 的 output.publicPath。
// 部署到 https://example.com/my-app/ 时
export default defineConfig({ base: "/my-app/" });
// 也可用命令行临时覆盖:vite build --base=/my-app/
// 相对部署(同一份产物放任意目录)可用:base: "./"
server.proxy 基于 http-proxy,用于在开发期把请求转发到后端,从而绕过浏览器的同源策略(浏览器限制的是「页面源 → 目标源」,而服务器之间的转发不受此限制):
server: {
proxy: {
"/api": {
target: "http://localhost:8080",
changeOrigin: true, // 让后端收到的 Host 是目标地址
rewrite: (p) => p.replace(/^\/api/, ""),
// 需要 WebSocket 时(如 socket.io)
ws: true,
// 后端用自签证书时
secure: false,
},
},
},
代理只解决开发跨域
server.proxy只在本地 dev server 生效,生产环境不存在代理。上线后要么前后端同源(Nginx 同域名反代),要么后端配置 CORS。跨域本质与缓存策略见 前端-04-浏览器与HTTP。
6.6 常用插件
| 插件 | 用途 |
|---|---|
@vitejs/plugin-vue | Vue 单文件组件编译 + HMR |
@vitejs/plugin-react | React JSX + Fast Refresh(基于 Babel) |
@vitejs/plugin-react-swc | 同上,用 SWC 提速 |
@vitejs/plugin-legacy | 为老浏览器生成兼容产物(额外一份 legacy bundle) |
vite-plugin-svg-icons / vite-svg-loader | SVG 图标雪碧图 / 当组件用 |
unplugin-auto-import / unplugin-vue-components | 自动导入 API 与组件 |
rollup-plugin-visualizer | 产物体积可视化分析 |
vite-plugin-compression | 预生成 gzip / brotli 文件供 Nginx 直接返回 |
Vite 生产产物分析
vite build只给一行体积汇总。要看清「谁占了 500KB」,用rollup-plugin-visualizer生成交互式 treemap,或用vite-bundle-analyzer。分析结论通常指向两类问题:整包引入的 UI 库、没做懒加载的重型依赖(如 ECharts、PDF 预览)。
七、Vite 与 Webpack 对比
| 维度 | Vite | Webpack |
|---|---|---|
| 冷启动(中大型项目) | 通常 级,秒级 | 随规模增长,常见 10–60 秒 |
| HMR 表现 | 极快,模块级精确失效 | 较快,但受 loader 链影响;大项目有延迟 |
| 开发原理 | 原生 ESM 按需编译 + esbuild 预构建 | 全量打包到内存 |
| 生产打包器 | Rollup | 自研 |
| 配置复杂度 | 低,约定优于配置,开箱即用 | 高,灵活但概念多 |
| 生态成熟度 | 快速成长,主流框架官方支持 | 最成熟,插件与历史方案最全 |
| 灵活性 | 中,复杂需求需写插件 | 极高,几乎任何定制都能实现 |
| 非标准场景 | 需要插件适配 | 原生支持(如自定义 Module Federation、多目标构建) |
| 构建产物优化 | 默认已很好,细粒度控制略弱 | 控制力最强(分包、Loader、Plugin 可编程) |
| 学习曲线 | 平缓 | 陡峭 |
| 当前主流版本 | Vite 8.x(以官方最新文档为准) | Webpack 5.x(以官方最新文档为准) |
7.1 新项目为什么优先选 Vite
- 启动与反馈快:改一行代码几乎立即看到结果,长时间迭代的体验差距非常明显。
- 默认配置合理:TS、JSX、CSS 预处理器、资源处理、
base、环境变量等开箱可用,配置文件通常只有几十行。 - 主流框架官方推荐:Vue、React 的脚手架(
create-vue、npm create vite)默认就是 Vite;Nuxt 3、SvelteKit、Astro 等元框架都以 Vite 为底座。 - 生产端不牺牲质量:底层是 Rollup,产物质量与 Tree Shaking 表现优秀。
7.2 什么样的老项目还该留在 Webpack
| 情形 | 为什么 |
|---|---|
| 深度定制的构建流程 | 自研 loader/plugin、特殊资源处理链,迁移成本 > 收益 |
| 依赖 Module Federation 的微前端 | Webpack 5 的模块联邦生态最成熟 |
| 非浏览器目标 | 打包 Node 服务、Electron 主进程、Web Worker 混合构建等 |
| 需要 CommonJS 原生兼容 | 大量老依赖且不便预构建 |
| 团队熟悉度与稳定性优先 | 迁移风险高于收益,业务迭代更值钱 |
| 巨型 Monorepo 且构建已高度调优 | 已有持久化缓存、并行构建方案 |
选型结论
新项目默认 Vite;存量 Webpack 项目按「收益 / 风险」决定是否迁移,不做无意义的追新。迁移通常按「先新页面用 Vite、老页面留 Webpack」的渐进方式做,比一次性重写配置稳妥得多。
八、其他构建工具定位
版本与能力均在快速演进,以下定位以官方最新文档为准
| 工具 | 语言实现 | 定位 | 特点 |
|---|---|---|---|
| esbuild | Go | 极快的转译与压缩 | 比 JS 实现快一到两个数量级;插件生态较弱,适合当底层引擎 |
| SWC | Rust | 转译 + 压缩 | Babel 的 Rust 替代品,Next.js、Vite 插件常用 |
| Rspack | Rust | Webpack 的兼容替代 | 尽量兼容 Webpack 配置与 loader/plugin API,迁移成本低 |
| Turbopack | Rust | Next.js 的新一代打包器 | 增量计算为核心,面向大型应用与增量构建 |
| Rolldown | Rust | Rollup 的 Rust 版 | 目标是让 Vite 开发与生产共用同一套打包内核 |
| Parcel | JS/Rust | 零配置打包器 | 开箱即用,适合小项目与原型 |
一个实用的判断:「速度」正在被 Rust/Go 重写,「配置兼容」正在被 Rspack 承接,「开发/生产统一内核」是 Vite 系的方向。学习时把精力放在「依赖图、转译、分包、缓存」这些不变的概念上,工具换掉也不会白学。
九、package.json 中 scripts 的常见写法
{
"name": "my-app",
"private": true,
"type": "module",
"scripts": {
// 【开发】--host 暴露局域网,方便手机真机调试
"dev": "vite --host",
// 【构建】先做类型检查再打包:类型错误不应被 esbuild 的"只转译"掩盖
"build": "tsc --noEmit && vite build",
// 【构建(跳过类型检查)】CI 里已单独跑过 tsc 时用,节省时间
"build:only": "vite build",
// 【预览】本地跑一遍生产产物,验证 base、路由回退、环境变量是否正确
"preview": "vite preview --port 4173",
// 【分析】产物体积
"build:analyze": "cross-env ANALYZE=1 vite build",
// 【测试与规范】
"test": "vitest run",
"test:watch": "vitest",
"lint": "eslint . --max-warnings=0",
"lint:fix": "eslint . --fix",
"format": "prettier --write .",
"typecheck": "tsc --noEmit",
// 【Webpack 项目对应写法】
"dev:webpack": "webpack serve --mode development",
"build:webpack": "webpack --mode production"
}
}
几点经验:
build里带不带tsc:Vite 用 esbuild 转译时不做类型检查,所以tsc --noEmit必须单独跑一次,否则类型错误会一路带到线上。- CI 用
npm ci而不是npm install:按 lockfile 精确安装,保证可复现(见 工具-03-包管理器)。 - 加
prebuild/predev钩子:可在启动前自动生成版本号、校验环境变量。 - 跨平台环境变量用
cross-env,不要写NODE_ENV=production vite build(Windows 的 cmd 不认)。
十、构建产物部署要点
10.1 哈希文件名与缓存策略
Vite/Rollup 与 Webpack 都能生成内容哈希文件名(如 index-a1b2c3d4.js)。内容不变 → 哈希不变 → 可以放心设置长缓存:
# 带哈希的静态资源:一年强缓存,immutable 表示"绝不会变"
location /assets/ {
expires 1y;
add_header Cache-Control "public, max-age=31536000, immutable";
}
# HTML 入口:绝不缓存,否则用户永远拿不到新的资源引用
location = /index.html {
add_header Cache-Control "no-cache, no-store, must-revalidate";
}
缓存配置最常见的错误
把
index.html也设成长缓存,结果是「发了新版本,用户还在加载旧 HTML,引用的是已被删除的旧哈希文件」→ 白屏。HTML 短缓存(或协商缓存)+ 资源文件长缓存是唯一正确的组合。
10.2 base 与 CDN
- 产物放 CDN 目录
https://cdn.example.com/app/:设base: "https://cdn.example.com/app/"或 Nginx 侧做路径重写。 - 部署到子路径
https://example.com/my-app/:设base: "/my-app/"。 - 不确定部署路径时可用
base: "./"生成相对路径产物,代价是无法在深层路由下正确解析(需要服务端配合)。 - 改了
base一定要用vite preview或真实环境验证,本地dev不受base影响,很容易「本地好、线上 404」。
10.3 SPA 路由回退
SPA 只有一个 index.html,但用户可能直接访问 /user/42 或刷新该地址。服务器必须把「找不到的路径」交回 index.html,由前端路由接管:
server {
listen 80;
server_name example.com;
root /var/www/app/dist;
# 静态资源直接命中文件;找不到就交给 index.html
location / {
try_files $uri $uri/ /index.html;
}
# API 反向代理到后端,与前端同源,从根上避免跨域
location /api/ {
proxy_pass http://127.0.0.1:8080/;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
}
哈希路由与历史路由的部署差异
用
createWebHashHistory(URL 带#)时无需服务端回退,因为#后的内容不发给服务器;用createWebHistory(History API)必须配置try_files回退,否则刷新 404。开发期由historyApiFallback(Webpack)或 Vite dev server 自动处理,这也解释了「为什么本地刷新正常、上线就 404」。
部署流程、反向代理、环境变量与灰度发布的完整方法见 后端-08-部署与运维基础;容器化上线见 后端-07-Docker与容器化。
十一、常见坑
Vite / Webpack 高频踩坑清单
1. Vite 项目不报类型错误:esbuild 只转译不做类型检查,必须单独跑
tsc --noEmit,或在 CI 里作为独立步骤。2.
base忘改导致线上 404:本地 dev 走绝对路径/src/...,不受base影响;只有build+ 部署到子目录才暴露问题。3.
public与src/assets混用:public里的文件不会哈希、不能被import,误用会导致缓存失效或路径错误。4.
import.meta.env改了不生效:它是构建期静态替换,需重启 dev server;并且只有VITE_前缀的变量可见。5. 把密钥写进前端环境变量:任何进产物的字符串都等于公开,密钥必须留在后端。
6. Tree Shaking 失效:CommonJS 依赖、默认导入整包(
import _ from "lodash")、sideEffects声明缺失三选一。7.
node_modules未排除:module.rules里漏写exclude: /node_modules/,构建时间暴涨甚至转译报错。8. 开发代理被误认为解决跨域:
server.proxy只在开发期生效,生产必须靠同源反代或 CORS。9. SPA 刷新 404:History 路由未配
try_files/historyApiFallback。10. 产物过大却只看总体积:用可视化分析定位具体依赖;常见元凶是整包引入的 UI 库与 3D/图表库。
11.
splitChunks过度拆分:产生上百个小 chunk,请求数与 HTTP/2 压力反而更差。12. HMR 不生效:检查
output.publicPath/server.hmr配置,以及是否有模块未提供 accept 边界而静默整页刷新。13. Source Map 误发生产:
sourcemap: true会把源码结构暴露到公网,生产建议"hidden"并只上传到错误监控平台。14. 忽略
engines与 Node 版本:新版 Vite 对 Node 版本有最低要求,版本不匹配会报奇怪的错误。
十二、练习题
练习 1:为什么裸模块名加载不了
用浏览器直接打开一个含
<script type="module" src="./main.js">的页面,其中main.js第一行是import dayjs from "dayjs";。请解释为什么浏览器会报错,并说明 Webpack 与 Vite 分别用什么机制解决它(提示:从「浏览器把 import 说明符当什么」入手)。
练习 2:手写一份最小配置
给定需求:TypeScript + CSS + 图片资源,用一个
index.html模板生成入口。请分别写出 15 行以内的 Webpack 配置 与 15 行以内的 Vite 配置,并指出两者在「哪些东西需要显式配置」上的差异。
练习 3:诊断 Tree Shaking 失效
某个项目打包后总体积 1.8MB,其中
lodash占 500KB。代码里只用了debounce。请列出至少三种可能原因,并给出对应的修复写法。
练习 4:分包策略设计
一个后台管理系统,依赖
vue、vue-router、pinia、echarts、element-plus,且echarts只在一个报表页用到。请设计 chunk 划分方案(说明每个 chunk 放什么、为什么),并估算首屏需要下载哪些 chunk。
练习 5:部署排查
现象:本地
npm run dev一切正常;执行npm run build后把dist放到https://example.com/admin/下,页面白屏且控制台报GET https://example.com/assets/index-xxx.js 404。请按步骤列出排查方向与修复方法(至少 3 条)。
十三、FAQ
Q1:Vite 开发不打包,那它还算打包器吗?生产为什么又要打包?
开发态不打包是为了速度:按需编译让启动时间与项目规模解耦;生产态打包是为了体积与缓存:压缩、Tree Shaking、少量长缓存文件带来的收益远大于构建耗时。所以 Vite 是「开发用原生 ESM + 生产用 Rollup」的组合方案,而不是「不打包」。
Q2:
loader和plugin到底怎么区分?一句话:loader 处理文件,plugin 处理流程。loader 的输入输出都是模块源码(),配置在
module.rules里;plugin 通过apply(compiler)挂到构建生命周期的钩子上,能做生成 HTML、注入变量、分析产物等 loader 做不到的事。碰到「转换某类文件」想 loader,碰到「改变构建行为」想 plugin。
Q3:构建很慢,我该从哪里优化?
按性价比排序:① 换更快的转译器(SWC / esbuild 替代 Babel /
ts-loader并配合transpileOnly);② 打开持久化缓存(Webpack 的cache: { type: "filesystem" }、Vite 的optimizeDeps缓存);③ 检查有没有误把大目录纳入module.rules(漏写exclude);④ 减少不必要的 Source Map 精度;⑤ 评估是否迁移到 Vite / Rspack。先测出瓶颈在哪一步(用--profile或speed-measure-webpack-plugin),再动手。
Q4:Monorepo 里多个包互相引用,构建怎么安排?
常见做法是用工作区(pnpm workspace / npm workspaces)统一依赖,内部包以源码形式被应用直接消费(Vite 可通过
resolve.alias或包的exports指向src),发布时再单独构建产出dist与类型声明。要点是:避免「改了 A 包却没重建 A,B 包仍在用旧产物」,可以用项目引用(TypeScript Project References)或构建编排工具(Turborepo / Nx)来管理依赖顺序与增量。包管理与版本约定见 工具-03-包管理器。
相关笔记
- JavaScript-06-模块化与工程化 —— CommonJS 与 ESM 的差异,是理解 Tree Shaking 与打包器行为的前提
- 前端-05-TypeScript —— TS 需要转译,是引入构建工具最直接的动机之一
- 后端-08-部署与运维基础 —— 产物上线后的反向代理、缓存、环境变量与灰度发布
- 前端-04-浏览器与HTTP —— 请求数、缓存头、跨域与渲染流程,决定了构建产物的优化方向
- 前端-09-前端工程化与调试 —— 规范、格式化、性能优化与错误监控
- 工具-03-包管理器 ——
package.json、lockfile、npm ci与语义化版本 - 版本与官方资源速查 —— 各技术栈当前版本号与官方文档入口
参考来源
- Vite 官方文档:<https://vite.dev/guide/>
- Vite 配置参考:<https://vite.dev/config/>
- Webpack 官方概念篇:<https://webpack.js.org/concepts/>
- Webpack 配置参考:<https://webpack.js.org/configuration/>
- MDN 中文 · JavaScript 模块:<https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Guide/Modules>
- Vue 官方文档 · 工具链:<https://cn.vuejs.org/guide/scaling-up/tooling.html>
版本说明
本篇以 Vite 8.x、Webpack 5.x、TypeScript 7.0 为背景写作,版本号来自本库 版本与官方资源速查 的核实结果。构建工具迭代较快(尤其 Turbopack、Rspack、Rolldown 等新内核),涉及具体版本、默认值与插件 API 的内容以官方最新文档为准。