w wyl123ly 的博客
MD

前端-08-构建工具-Vite与Webpack

46 KB 2026.10.11 原文件

前端-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 对应概念
入口从哪开始找依赖entrybuild.rollupOptions.input
解析裸名 → 路径、扩展名补全、别名resolve.extensions / alias同左(内部用 Rollup 插件)
加载转换把非 JS 内容变成 JS 模块module.rules 里的 loader内置转换 + 插件
依赖图记录谁引用谁Compilation / ModuleGraphModuleGraph
分块拆成多个输出文件optimization.splitChunksbuild.rollupOptions.output.manualChunks
优化删死代码、压缩mode: "production" + Terseresbuild/Rollup 内置
产物写文件、注入 HTMLoutput + HtmlWebpackPluginbuild.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 的区别是最常考的面试题:

维度loaderplugin
作用粒度单个文件(模块)整个构建过程
配置位置module.rulesplugins 数组
本质一个转换函数 一个带 apply(compiler) 的类
典型例子ts-loader、css-loader、file-loaderHtmlWebpackPlugin、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-loaderloaderTS / 新语法转译
css-loaderloader解析 CSS 的 @import 与 url()
style-loaderloader把 CSS 以 <style> 注入 DOM
postcss-loaderloader接 Autoprefixer、Tailwind 等 PostCSS 插件
sass-loader / less-loaderloaderSCSS / Less 编译
asset / asset/resource(内置)内置模块类型图片、字体等静态资源
HtmlWebpackPluginplugin生成 HTML 并注入产物引用
MiniCssExtractPluginplugin生产环境抽离独立 CSS 文件
DefinePlugin(内置)plugin注入编译期常量
CopyWebpackPluginplugin原样拷贝静态文件
BundleAnalyzerPluginplugin可视化产物体积构成
ForkTsCheckerWebpackPluginplugin独立进程做 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(摇树优化)指删除「被导出但没人引用」的死代码。它有三个前提,缺一不可:

  1. 必须使用 ES Module(ESM)语法。import/export 是静态结构,打包器能分析出谁用了谁;CommonJS 的 require 是运行时求值,无法可靠静态分析。
  2. sideEffects 声明要正确。在 package.json 里写:

```json

{ "sideEffects": false }

```

表示「这个包的所有文件都没有副作用,没用到的可以放心删」。若包里有全局注册、polyfill 等副作用文件,必须列出来:

```json

{ "sideEffects": ["*.css", "./src/polyfill.ts"] }

```

  1. 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.developmentvite dev开发专用
.env.productionvite 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-vueVue 单文件组件编译 + HMR
@vitejs/plugin-reactReact JSX + Fast Refresh(基于 Babel)
@vitejs/plugin-react-swc同上,用 SWC 提速
@vitejs/plugin-legacy为老浏览器生成兼容产物(额外一份 legacy bundle)
vite-plugin-svg-icons / vite-svg-loaderSVG 图标雪碧图 / 当组件用
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 对比

维度ViteWebpack
冷启动(中大型项目)通常 级,秒级随规模增长,常见 10–60 秒
HMR 表现极快,模块级精确失效较快,但受 loader 链影响;大项目有延迟
开发原理原生 ESM 按需编译 + esbuild 预构建全量打包到内存
生产打包器Rollup自研
配置复杂度低,约定优于配置,开箱即用高,灵活但概念多
生态成熟度快速成长,主流框架官方支持最成熟,插件与历史方案最全
灵活性中,复杂需求需写插件极高,几乎任何定制都能实现
非标准场景需要插件适配原生支持(如自定义 Module Federation、多目标构建)
构建产物优化默认已很好,细粒度控制略弱控制力最强(分包、Loader、Plugin 可编程)
学习曲线平缓陡峭
当前主流版本Vite 8.x(以官方最新文档为准)Webpack 5.x(以官方最新文档为准)

7.1 新项目为什么优先选 Vite

  1. 启动与反馈快:改一行代码几乎立即看到结果,长时间迭代的体验差距非常明显。
  2. 默认配置合理:TS、JSX、CSS 预处理器、资源处理、base、环境变量等开箱可用,配置文件通常只有几十行。
  3. 主流框架官方推荐:Vue、React 的脚手架(create-vue、npm create vite)默认就是 Vite;Nuxt 3、SvelteKit、Astro 等元框架都以 Vite 为底座。
  4. 生产端不牺牲质量:底层是 Rollup,产物质量与 Tree Shaking 表现优秀。

7.2 什么样的老项目还该留在 Webpack

情形为什么
深度定制的构建流程自研 loader/plugin、特殊资源处理链,迁移成本 > 收益
依赖 Module Federation 的微前端Webpack 5 的模块联邦生态最成熟
非浏览器目标打包 Node 服务、Electron 主进程、Web Worker 混合构建等
需要 CommonJS 原生兼容大量老依赖且不便预构建
团队熟悉度与稳定性优先迁移风险高于收益,业务迭代更值钱
巨型 Monorepo 且构建已高度调优已有持久化缓存、并行构建方案

选型结论

新项目默认 Vite;存量 Webpack 项目按「收益 / 风险」决定是否迁移,不做无意义的追新。迁移通常按「先新页面用 Vite、老页面留 Webpack」的渐进方式做,比一次性重写配置稳妥得多。

八、其他构建工具定位

版本与能力均在快速演进,以下定位以官方最新文档为准

工具语言实现定位特点
esbuildGo极快的转译与压缩比 JS 实现快一到两个数量级;插件生态较弱,适合当底层引擎
SWCRust转译 + 压缩Babel 的 Rust 替代品,Next.js、Vite 插件常用
RspackRustWebpack 的兼容替代尽量兼容 Webpack 配置与 loader/plugin API,迁移成本低
TurbopackRustNext.js 的新一代打包器增量计算为核心,面向大型应用与增量构建
RolldownRustRollup 的 Rust 版目标是让 Vite 开发与生产共用同一套打包内核
ParcelJS/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 的内容以官方最新文档为准。