序章：开启前端工程化之旅——从为何需要到如何学习

0.1. 欢迎来到“施工现场”：为什么我们不能只写 HTML/CSS/JS？

曾几何时，网页开发是一件相对纯粹的事情：一个 .html 文件，链入一个 .css 文件和几个 .js 文件，一个“网页”就诞生了。然而，随着 Web 从简单的“信息展示页面”进化为功能强大的“应用程序”（Web App），我们的开发模式也必须经历一场深刻的革命。

我们面临的挑战是全新的：

• 规模化与协作: 如何将一个庞大的应用拆分成上百个独立的 组件化 单元，并让多人高效地协同开发？
• 代码组织: 如何科学地组织成千上万的 JavaScript 模块化 文件，避免命名冲突和依赖地狱？
• 性能与兼容性: 如何使用最新的 JavaScript 语法（ESNext）提升开发效率，同时又保证代码能在旧款浏览器上平稳运行？如何将上百个资源文件优化、压缩成浏览器最高效加载的形式？

这些挑战，都无法通过简单编写 HTML/CSS/JS 来解决。我们需要一套更强大、更规范的流程和工具，这就是 前端工程化 的由来。它意味着我们将代码的“开发阶段”和最终的“运行阶段”明确分开。我们写的代码是便于自己和团队维护的“源码”，而交给浏览器的，是经过一系列自动化工具处理过的、最优化的“产物”。

而连接“源码”和“产物”的桥梁，就是我们接下来要学习的——前端工具链。

0.2. 建立全局视野：分阶段学习路线图与前置知识建议

面对繁多的工具，最有效的学习方式就是手持一张地图，明确自己的位置和前进的方向。本知识库将遵循一条从基础到前沿的清晰路径，我们强烈建议您按照以下两个阶段进行学习：

第一阶段：前端工程化的通用基石 (第 1 ~ 7 章)

这个阶段的内容，是任何现代前端开发者都必须掌握的通用基础，它不依赖任何特定的前端框架（如Vue/React），只需要您具备扎实的 JavaScript 基础知识即可顺利学习。

• 环境与基础 (第 1-2 章): 我们将学习所有工作的起点——如何在你的电脑上配置一个稳定、灵活的开发环境。
• 依赖管理 (第 3-6 章): 这是工程化的核心。我们将深入 package.json，理解 lock 文件的契约精神，对比各大包管理工具，并初探企业级的 Monorepo 模式。
• 构建理论 (第 7 章): 我们将通过亲手实践，揭开“构建”的神秘面纱，理解代码是如何被转换、打包和优化的。

第二阶段：现代构建工具深度实践 (第 8 ~ 10 章)

当您准备好后，就可以进入更高阶的学习。这个阶段我们将深入现代构建工具的核心。

• 温故知新 (第 8 章): 我们会回顾 Webpack 的经典思想，理解其设计哲学与历史局限。
• 核心精通 (第 9 章): 我们将深入掌握现代前端引擎 Vite 的方方面面，从工作原理到插件开发。
• 未来展望 (第 10 章): 最后，我们将一同展望 2025 年及以后的前端工具趋势。

0.3. 核心学习方法：理解每个工具诞生时所要解决的核心“痛点”

最后，请在开始学习前，务必在心中建立一个最重要的思维模型：所有工具的出现，都是为了解决一个特定的问题。

在后续的章节中，我们将始终遵循这一“问题驱动”的模式。对于每一个工具，我们都会先剖析它所要解决的“痛点”，然后再介绍它的解决方案和使用方法。

第一章：搭建稳固基石——精通 Node.js 版本管理 (NVM)

在本章中，我们将首先解决所有 Node.js 开发者都会遇到的第一个，也是最棘手的问题——环境管理。我们将按照以下步骤，一劳永逸地解决它：

1. 首先，我们将进行 彻底的环境清理，为 NVM 的安装扫清障碍。
2. 接着，我们将 图文并茂地安装和配置 nvm-windows，并为其配置国内高速下载源。
3. 最后，我们将通过 核心命令实践，熟练掌握多版本 Node.js 的安装、查看与切换，并了解团队协作中的最佳实践。

1.1. 准备工作：彻底卸载已有的 Node.js

在安装 NVM 之前，最重要的一步是确保您的系统中没有其他方式安装的 Node.js 版本，否则会引起严重的冲突。

第一步：通过控制面板卸载

1. 打开 Windows 的“控制面板”。
2. 进入“程序和功能”。
3. 在右上角的搜索框中输入 node。
4. 找到 Node.js 程序，右键点击，选择“卸载”。

第二步：检查并删除残留文件

卸载程序运行完毕后，请检查以下目录，如果仍然存在，请手动删除它们：

• C:\Program Files\nodejs
• C:\Program Files (x86)\nodejs
• C:\Users\{你的用户名}\AppData\Roaming\npm
• C:\Users\{你的用户名}\AppData\Roaming\npm-cache

第三步：清理环境变量

1. 右键点击“此电脑” -> “属性” -> “高级系统设置” -> “环境变量”。
2. 在“系统变量”和“用户变量”的 Path 中，检查是否存在任何与 nodejs 相关的条目，如果存在，请选中并删除。

1.2. 详解：安装 nvm-windows

第一步：下载 nvm-windows 安装包

nvm-windows 是一个社区维护的开源项目，我们需要从它的官方 GitHub 仓库下载安装程序。

请选择最新的 nvm-setup.zip 文件进行下载。

第二步：运行安装程序

解压下载的 nvm-setup.zip 文件，双击 nvm-setup.exe 启动安装向导。

第三步：选择 NVM 安装路径

安装程序会要求您选择 NVM 的安装路径。

第四步：选择 Node.js 符号链接路径

接下来，程序会要求您选择 Node.js 的符号链接路径。这个路径将作为系统当前激活的 Node.js 的“快捷方式”。同样，确保路径不含中文和空格，推荐使用默认值。

点击“Next”并完成安装。安装程序会自动为您配置好所需的环境变量。

第五步：验证安装

安装完成后，务必重新打开一个新的终端窗口（如 PowerShell 或 CMD），让新的环境变量生效。输入以下命令：

1

nvm version

看到版本号即表示 nvm-windows 安装成功！

1.3. 国内用户福利：配置高速下载镜像

默认情况下，NVM 会从国外的 nodejs.org 下载 Node.js，速度可能较慢。我们可以通过修改配置文件，将其指向速度更快的国内镜像。

第一步：找到 settings.txt 文件

在终端输入 nvm root 命令，可以查看到 NVM 的安装路径。

1

nvm root

1

Current Root: C:\Users\YourUser\AppData\Roaming\nvm

根据显示的路径，找到并打开 settings.txt 文件。

第二步：修改配置文件

在 settings.txt 文件末尾添加以下两行，使用最新的淘宝 NPM 镜像源：

1
2

node_mirror: https://npmmirror.com/mirrors/node/
npm_mirror: https://npmmirror.com/mirrors/npm/

保存文件后，NVM 下载 Node.js 的速度将得到极大提升。

1.4. 核心命令实践：安装与切换 Node.js

1. 查看可安装的版本

1

nvm list available

该命令会列出所有可供下载的 Node.js 版本。

2. 安装指定版本
我们来安装一个长期支持版（LTS）和一个较新的版本，例如：

1
2

nvm install 20.17.0 # 一个稳定的 LTS 版本
nvm install 22.5.1  # 一个较新的版本

3. 查看已安装版本

1

nvm ls

1
2

#     22.5.1
#   * 20.17.0 (Currently using 64-bit)

星号 * 表示当前终端会话正在使用的版本。

4. 切换使用版本

1
2

nvm use 22.5.1
# Now using node v22.5.1 (64-bit)

验证一下版本是否切换成功：

1
2
3

node -v && npm -v
# v22.5.1
# v10.8.1

版本已成功激活！

1.5. 团队协作的“默契”：.nvmrc 文件的规范化应用

为了保证团队成员使用统一的 Node.js 版本，我们可以在项目根目录下创建一个 .nvmrc 文件，声明项目所需的版本。

文件路径: my-new-project/.nvmrc

1

22.5.1

当团队成员进入该项目目录后，只需在终端执行 nvm use，即可自动切换到 .nvmrc 文件所指定的版本，极大提升了协作效率。

1.6. 本章核心速查总结

1.7. 高频面试题与陷阱

第二章：项目初始化——理解 NPM 与你的第一个依赖包

在本章中，我们将循序渐进，像建筑师打地基一样，稳固地构建我们的工程化知识体系：

1. 首先，我们将澄清 Node.js 在前端开发中的真实角色，消除您的疑惑。
2. 接着，我们将通过类比，轻松理解 包 (Package) 和 NPM 的核心理念。
3. 最后，我们将进行一次 完整的动手实践，让理论知识落地生根，并为您揭开下一章的核心——package.json。

2.1. Node.js：现代前端开发的幕后基石

许多初学者在接触 Vue 或 React 等现代框架时，都会遇到第一个门槛：被要求先在电脑上安装 Node.js。这自然会引发疑问，因为 Node.js 广为人知的是其作为服务器端运行时的角色。

实际上，在前端工程化的领域里，Node.js 扮演的是一个“幕后英雄”的角色。我们依赖它，并非是要用它编写网站的后端服务，而是要利用其提供的强大 开发生态系统。它如同一个现代化的厨房，为我们前端开发者（大厨）提供了高效烹饪（构建应用）所需的一切工具。

具体来说，Node.js 为前端开发提供了三大核心能力：

• 1. 包管理能力: Node.js 自带了 npm（Node Package Manager），这是全球最大的软件库。有了它，我们可以轻松地一键下载、管理项目需要的所有第三方代码库（例如 React, axios 等）。
• 2. 构建工具运行环境: 现代前端开发离不开各种能让我们代码变得更强大的工具（如 Vite, Webpack）。这些工具本身就是用 JavaScript 编写的程序，它们需要在 Node.js 这个“运行时环境”中才能执行。
• 3. 本地开发服务器: 在开发过程中，我们需要一个本地的 Web 服务器来预览我们的应用。Node.js 生态中的工具（如 Vite）可以快速启动一个功能强大的开发服务器，支持热更新等高级功能。

2.2. 模块化开发的基石：理解“包”与“包管理器”

在过去，向项目中添加一个第三方库（如 jQuery）通常意味着手动下载 .js 文件、复制粘贴、然后通过 <script> 标签引入。这个过程不仅繁琐，在库版本更新时更是一场灾难。

为了解决这一原始的协作方式，社区引入了 包 (Package) 和 包管理器 (Package Manager) 的概念，奠定了现代模块化开发的基础。

• 包 (Package): 一个“包”是为解决特定问题而封装好的代码集合。它可以是一个 UI 组件库（如 Ant Design），一个工具函数库（如 Lodash），或是一个完整的框架（如 Vue）。您可以把它想象成一块功能明确的“乐高积-木”，具备开箱即用的能力。

• 包管理器 (Package Manager): 它是管理这些“乐高积木”的智能工具。其核心职责包括：

  • 依赖解析: 知道去哪里（通常是 NPM Registry，全球最大的“乐高仓库”）找到你需要的包。
  • 下载与安装: 能将你指定的包及其所有依赖（依赖的依赖）一次性、自动化地下载到项目中。
  • 版本控制: 记录每个包的精确版本，确保团队成员和生产环境的依赖一致性。
  • 生命周期管理: 提供更新、卸载等一系列管理命令。

2.3. 第一次实践：初始化项目与安装依赖

理论介绍完毕，现在让我们亲手实践。我们将从零开始创建一个项目，并安装 lodash 这个强大的工具库。

目标文件结构预览：

1
2
3
4
5
6
7
8
9

# 操作前，你只有一个空文件夹
# my-first-node-project/

# 操作后，你的文件夹将变成这样
# my-first-node-project/
├── node_modules/         # <-- npm 自动创建，存放所有下载的包
├── index.js              # <-- 我们自己创建的业务逻辑文件
├── package-lock.json     # <-- npm 自动创建，锁定依赖版本
└── package.json          # <-- npm 自动创建，项目配置文件

1. 创建并进入项目目录

打开你的终端（推荐在 Windows 上使用 PowerShell 或 Windows Terminal），执行以下命令：

1
2
3
4
5

# 创建一个名为 my-first-node-project 的文件夹
mkdir my-first-node-project

# 进入这个文件夹
cd my-first-node-project

2. 初始化项目，生成 package.json

执行 npm init 命令来创建 package.json 文件。这个文件是项目的“身份证”，记录着项目名称、版本、依赖等元信息。使用 -y 参数可以跳过问答环节，快速生成默认配置。

1

npm init -y

执行后，你的 package.json 文件内容会类似于：

1
2
3
4
5
6
7
8
9
10
11
12

{
  "name": "my-first-node-project",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC"
}

3. 安装依赖包

现在，我们来安装 lodash。它是一个非常流行的 JavaScript 工具库，提供了大量便捷的函数。

1

npm install lodash

命令执行完毕后，你会发现文件夹里新增了 node_modules 目录和 package-lock.json 文件。同时，package.json 文件也被自动更新，增加了一个 dependencies 字段：

1
2
3
4
5
6

{
  ...
  "dependencies": {
    "lodash": "^4.17.21"
  }
}

4. 编写并运行代码

在 my-first-node-project 文件夹中，创建一个名为 index.js 的新文件，并输入以下内容。我们将使用 lodash 里的 chunk 方法，它可以将一个数组按指定大小进行分割。

文件路径: my-first-node-project/index.js

1
2
3
4
5
6
7
8
9
10
11
12

// 1. 在 Node.js 环境中，使用 require 语法引入我们安装的 lodash 包
const _ = require('lodash');

// 2. 定义一个数组
const numbers = [1, 2, 3, 4, 5, 6, 7, 8];

// 3. 使用 lodash 的 chunk 方法，将数组每 3 个元素分为一组
const chunkedNumbers = _.chunk(numbers, 3);

// 4. 打印结果
console.log('原始数组:', numbers);
console.log('使用 lodash 分割后的数组:', chunkedNumbers);

在终端中执行以下命令来运行这个文件：

1

node index.js

5. 查看结果

1
2

原始数组: [ 1, 2, 3, 4, 5, 6, 7, 8 ]
使用 lodash 分割后的数组: [ [ 1, 2, 3 ], [ 4, 5, 6 ], [ 7, 8 ] ]

2.4. 悬念：package.json 的深度世界

你已经成功地运行了你的第一个 Node.js 项目。在这个过程中，package.json 文件被创建和修改，它像一个安静的管家，默默记录着一切。

我们已经看到了 name, version, 和 dependencies 字段。但是，这个文件远比表面看起来的要强大得多。

• scripts 字段里那句 "test": "..." 是什么意思？我们如何用它来自动化我们的工作流？
• dependencies 旁边是否还有其他的 dependencies？比如传说中的 devDependencies？它们有何区别？
• 这个文件还能定义项目的入口、作者、开源协议等等，它们又分别在何时起作用？
• package-lock.json 这个更复杂的文件又是做什么的？为什么它如此重要？

2.5. 本章核心速查总结

2.6. 高频面试题与陷阱

第三章：从配置到执行—— package.json 深度解析与命令行工具开发

3.1. 项目启动：从一个目标开始

我们的目标是创建一个简单的命令行工具：在终端输入命令，就能看到当前城市的天气。让我们从初始化项目开始。

1
2

mkdir weather-cli && cd weather-cli
npm init -y

我们得到了一个初始的 package.json，它将伴随我们整个开发过程。

3.2. 功能实现：dependencies 与 devDependencies 的天壤之别

3.2.1. 引入核心功能：dependencies

要查询天气，我们首先需要能发送网络请求。axios 是一个广受欢迎的 HTTP 客户端库。因为 我们的工具在运行时必须依赖它来获取数据，所以它是一个典型的 生产依赖 (dependencies)。

1

npm install axios

同时，为了让命令行输出更美观，我们引入 chalk 库来给文字添加颜色。同样，美化输出是工具核心功能的一部分，因此它也是 dependencies。

1

npm install chalk@4 # chalk v5+ 是纯 ESM 包，为保持 CommonJS 教程一致性，我们使用 v4

现在，package.json 看起来是这样：

1
2
3
4

"dependencies": {
  "axios": "^1.11.0",
  "chalk": "^4.1.2"
}

让我们编写核心代码 index.js 来使用它们：
文件路径: weather-cli/index.js

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

const axios = require('axios');
const chalk = require('chalk');

async function getWeather() {
    try {
        // 查询北京天气
        const response = await axios.get('http://t.weather.sojson.com/api/weather/city/101281001');
        
        if (response.data.status === 200) {
            const data = response.data.data;
            const today = data.forecast[0];
            console.log(chalk.blue(`当前温度: ${data.wendu}°C`));
            console.log(chalk.green(`天气状况: ${today.type}`));
            console.log(chalk.cyan(`湿度: ${data.shidu}`));
            console.log(chalk.magenta(`提示: ${today.notice}`));
            
        } else {
            console.error(chalk.red('天气数据获取失败'));
        }

    } catch (error) {
        console.error(chalk.red('获取天气失败:', error.message));
    }
}

getWeather();

现在运行它：

1

node index.js

1
2
3
4
今日详情:
温度范围: 低温 23℃ ~ 高温 29℃
风向风力: 东南风 2级
日期: 30

3.2.2. 优化开发体验：devDependencies

我们的核心功能已经完成。但作为工程师，我们还希望代码风格统一、开发流程更顺畅。

1. 代码格式化: 我们引入 prettier 来自动格式化代码。prettier 只在开发阶段 对源码进行格式化，最终用户运行的代码里并不需要它。
2. 自动重启: 我们引入 nodemon，它能监听文件变化并自动重启应用，省去手动 Ctrl+C 和 node index.js 的麻烦。nodemon 也只在开发阶段 使用。

因此，它们都是典型的 开发依赖 (devDependencies)。

1
2
3

npm install prettier nodemon --save-dev
# 或者使用简写 -D
# npm i prettier nodemon -D

现在，package.json 完整了：

1
2
3
4
5
6
7
8

"dependencies": {
  "axios": "^1.7.2",
  "chalk": "^4.1.2"
},
"devDependencies": {
  "nodemon": "^3.1.4",
  "prettier": "^3.3.2"
}

3.3. 一个“线上事故”：具象化理解 SemVer (^ ~)

我们的 weather-cli v1.0.0 开发完成，axios 的版本是 ^1.11.0。一切看起来很完美。
事故模拟:
一个月后，axios 发布了 1.12.0 版本。这个版本有一个微小的、不兼容的 API 变更（这在现实中不应发生，但我们以此为例），导致错误处理的方式变了。

• 你 (开发者 A): 你的 node_modules 里的 axios 还是 1.11.0，一切正常。
• 新同事 (开发者 B): 他今天刚加入项目，执行 npm install。因为版本号是 ^1.11.0，npm 为他安装了最新的 1.12.0 版本。
• 结果: 在处理网络异常时，新同事的 weather-cli 崩溃了，而你的却安然无恙。“在我这儿是好的啊！” 的经典场景再次上演。

这就是版本号中 ^ (Caret) 符号的威力与风险。它带来了自动获取 bug 修复和新特性的便利，也带来了潜在的不稳定性。

3.4. 自动化工作流：释放 scripts 的真正威力

现在，让我们利用 devDependencies 来为 weather-cli 创建一套专业的 scripts 工作流。

修改 package.json 的 scripts 字段：

1
2
3
4
5

"scripts": {
  "start": "node index.js",
  "dev": "nodemon index.js",
  "format": "prettier --write ."
}

• "start": "node index.js": 定义了项目的标准启动方式，用于生产环境或直接执行。
• "dev": "nodemon index.js": 定义了开发模式。nodemon 会在这里大显身手。当你修改并保存 index.js 时，它会自动重启应用。
• "format": "prettier --write .": 定义了一个代码格式化命令。--write . 表示让 prettier 格式化当前目录下的所有支持文件。

揭秘 npm run 的魔法:
你可能会问，我没有全局安装 nodemon 和 prettier，为什么 npm run 能找到它们？
原理: 当执行 npm run <脚本名> 时，npm 会自动将 ./node_modules/.bin 目录临时添加到系统 PATH 中。所有通过 npm 安装的可执行包（如 nodemon, prettier）的启动脚本都存放在这里，因此 npm 可以直接调用它们，避免了全局安装污染。

现在，你可以这样工作：

1. 开始开发: 运行 npm run dev，然后随意修改 index.js 的代码，终端会自动刷新。
2. 提交代码前: 运行 npm run format，确保代码风格整洁统一。
   3. 最终执行: 运行 npm start 来查看最终效果。

3.5. 从开发到部署：一个 CLI 工具的完整生命周期

我们已经开发出了 weather-cli 的核心功能，但要让它成为一个能 在任何终端直接通过命令执行 的专业工具，还需要经历本地测试、发布、安装等一系列关键流程。

3.5.1. 功能与执行力升级

第一步：代码升级，接收命令行参数

我们首先采纳您提供的更强大的 index.js 版本。它能通过 process.argv 接收用户输入的城市名，并使用了更真实的 API。

第二步：让脚本“可执行”：不可或缺的 Shebang

这是让一个 .js 文件从“普通脚本”蜕变为“可执行命令”最关键的一步。我们必须在 index.js 文件的 最顶端 添加一行特殊的注释：

#!/usr/bin/env node

• 它是什么？ 这行代码被称为 Shebang 或 Hashbang。
• 它做什么？ 它告诉操作系统（Linux, macOS, 以及 Windows 上的 Git Bash/WSL 等环境），当直接执行这个文件时，应该使用哪个解释器来运行它。#!/usr/bin/env node 的意思是：“请在当前用户的环境变量 PATH 中找到 node 程序，并用它来执行我下面的代码。”
• 没有它会怎样？ 如果没有这一行，当用户在终端输入 weather 时，操作系统不知道这是一个 Node.js 脚本，可能会尝试用默认的 shell 解释器来执行，从而导致语法错误或执行失败。

现在，让我们整合代码和 Shebang：

文件路径: weather-cli/index.js (请更新为以下最终代码)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43

#!/usr/bin/env node
const axios = require('axios');
const chalk = require('chalk');

async function getWeather(city = '潮州') { // 默认城市改为潮州
    try {
        // 使用一个公开的天气 API
        const cityCodeMap = {
            '北京': '101010100', '上海': '101020100', '广州': '101280101',
            '深圳': '101280601', '杭州': '101210101', '南京': '101190101',
            '成都': '101270101', '重庆': '101040100', '西安': '101110101',
            '武汉': '101200101', '潮州': '101281501'
        };

        const cityCode = cityCodeMap[city] || '101281501'; // 未找到城市则默认潮州
        
        const apiUrl = `http://t.weather.sojson.com/api/weather/city/${cityCode}`;
        const response = await axios.get(apiUrl);
        
        if (response.data.status === 200) {
            const data = response.data.data;
            const today = data.forecast[0];
            
            console.log(chalk.yellow(`城市: ${response.data.cityInfo.parent} - ${response.data.cityInfo.city}`));
            console.log(chalk.blue(`当前温度: ${data.wendu}°C`));
            console.log(chalk.green(`天气状况: ${today.type}`));
            console.log(chalk.cyan(`湿度: ${data.shidu}`));
            console.log(chalk.magenta(`空气质量: ${data.quality}`));
            console.log(chalk.gray(`更新时间: ${response.data.time}`));
            console.log(chalk.white(`\n今日详情: ${today.low} ~ ${today.high}, ${today.fx} ${today.fl}`));
        } else {
            console.error(chalk.red('天气数据获取失败'));
        }

    } catch (error) {
        console.error(chalk.red('获取天气失败:', error.message));
        console.log(chalk.yellow('提示: 可尝试的城市名称: 北京、上海、广州、深圳、杭州、南京、成都、重庆、西安、武汉'));
    }
}

// 从命令行参数的第三个元素获取城市名称 (第一个是 node, 第二个是脚本路径，所以我们要拿到真实参数一定是 [2])
const city = process.argv[2] || '潮州';
getWeather(city);

3.5.2. 本地测试：npm link 的妙用

在发布到 NPM 之前，我们如何在本地模拟一个真实的用户使用场景，直接测试 weather 命令呢？答案就是 npm link。它能在你的电脑上创建一个指向你项目源文件的“全局快捷方式命令”。

第一步：配置 bin 字段

修改 package.json，添加 bin 字段：

1
2
3
4
5
6
7
8

{
  ...
  "main": "index.js",
  "bin": {
    "weather": "./index.js"
  },
  ...
}

第二步：执行链接

在你的项目根目录 (weather-cli/) 下，执行：

1

npm link

1
added 1 package in 1s

第三步：全局测试

现在，打开任何一个新的终端窗口，你都可以像使用一个真正的全局命令一样使用 weather 了！

1

weather 深圳

1
2
3
4
5
6
7
城市: 广东 - 深圳
当前温度: 30°C
天气状况: 阵雨
湿度: 91%
空气质量: 优
更新时间: 2025-08-30T10:49:15
今日详情: 低温 26℃ ~ 高温 31℃, 无持续风向 1级

第四步：取消链接

当你本地测试完成，准备发布时，可以取消这个链接：

1

npm unlink

3.5.3. 走向世界：发布、安装与卸载

当本地测试万无一失后，我们就可以将它发布到 NPM 仓库，让所有人使用。

第一步：发布包 (模拟)

1
2
3
4
5

# 登录 NPM 账号 (需要提前在官网注册)
npm login

# 发布
npm publish

第二步：全局安装你自己的包

一旦发布成功，你和其他用户就可以通过 -g (global) 参数来全局安装这个工具了。

1

npm install -g weather-cli-prorise-demo

第三步：在任何地方使用

安装完成后，你就可以在电脑的任何路径下使用 weather 命令。

1

weather 广州

1
2
3
4
5
6
7
城市: 广东 - 广州
当前温度: 31°C
天气状况: 多云
湿度: 88%
空气质量: 良
更新时间: 2025-08-30T10:49:15
今日详情: 低温 26℃ ~ 高温 33℃, 无持续风向 2级

第四步：卸载全局包

如果不再需要这个工具，可以轻松地全局卸载它。

1

npm uninstall -g weather-cli-prorise-demo

卸载后，weather 命令将不再可用。

3.6. 本章核心速查总结

3.7. 高频面试题与陷阱

第四章：团队协作的“契约”——Lock 文件的确定性力量

4.1. “在我这儿是好的啊！”——依赖不确定性问题的根源

让我们回到上一章那个惊心动魄的事故现场：

• 项目背景: 我们的 weather-cli 项目在其 package.json 中依赖了 "axios": "^1.11.0"。
• 事故经过:
  1. 你（开发者 A）在 axios 最新版为 1.11.0 时创建了项目。
  2. 一个月后，axios 发布了存在微小兼容性问题的 1.12.0 版。
  3. 新同事（开发者 B）克隆项目后，执行 npm install。由于 ^ 允许次版本更新，npm 为他安装了 1.12.0 版。
  4. 结果，同一个项目，在你的电脑上运行正常，在新同事的电脑上却频繁崩溃。

这个问题的根源，正是 package.json 中版本号的 范围性质。^1.11.0 并没有指定一个精确的版本，而是给出了一个“可接受的范围”。虽然这为我们带来了自动更新小补丁的便利，但也引入了团队成员之间、以及开发环境与生产服务器之间 依赖版本不一致 的巨大风险。

4.2. package-lock.json：为你的项目依赖树拍下“快照”

当你第一次成功执行 npm install 后，npm 会自动在你的项目根目录创建一个 package-lock.json 文件。这个文件，正是解决上述问题的关键。

它详细记录了在生成该文件的那一刻，整个依赖树中每一个包（包括你直接依赖的，和你依赖的包所依赖的子孙包）的：

• version: 精确的版本号，没有任何 ^ 或 ~。
• resolved: 该版本包的实际下载地址。
• integrity: 一个基于文件内容的哈希值（Checksum），用于确保下载的包未经篡改，保证安全性。

让我们来看一下 weather-cli 项目中 package-lock.json 的一个片段：

1
2
3
4
5
6
7
8
9
10
11

"node_modules/axios": {
  "version": "1.11.0",
  "resolved": "https://registry.npmmirror.com/axios/-/axios-1.11.0.tgz",
  "integrity": "sha512-1Lx3WLFQWm3ooKDYZD1eXmoGO9fxYQjrycfHFC8P0sCfQVXyROp0p9PFWBehewBOdCwHc+f/b8I0fMto5eSfwA==",
  "license": "MIT",
  "dependencies": {
    "follow-redirects": "^1.15.6",
    "form-data": "^4.0.4",
    "proxy-from-env": "^1.1.0"
  }
},

观察要点：

1. 版本锁定：axios 的版本被精确地记录为 1.11.0，而不是 ^1.11.0。
2. 来源锁定：resolved 字段指明了它的确切下载来源。
3. 内容锁定：integrity 哈希确保了包的完整性。
4. 全树锁定：不仅 axios 被锁定，它自己的依赖 follow-redirects 等也被精确地锁定在了 1.15.6 版本。

4.3. 为什么 package-lock.json 必须提交到 Git 仓库？

因为 package-lock.json 才是团队依赖环境的“唯一真相来源”。

当 package-lock.json 文件存在时，npm install 的行为会发生改变。它会优先读取 lock 文件，并严格按照其中记录的版本、地址和哈希值去下载和构建 node_modules 目录。package.json 中的 ^ ~ 范围符在此时将被忽略。

• 如果不提交 lock 文件：每个团队成员、每台部署服务器在执行 npm install 时，都会根据自己的 package.json 重新计算依赖，生成一份 全新的、可能与他人不一致的 lock 文件和 node_modules。这又回到了我们最初的混乱状态。
• 如果提交了 lock 文件：所有环境（其他开发者、CI/CD 服务器）在执行 npm install 时，都会基于这份 共享的、一致的 lock 文件来构建 node_modules。从而保证了从开发到生产，整个团队的依赖环境是 像素级 的完全一致。

4.4. 面向 CI/CD 与团队协作的命令：npm ci

我们已经知道，当存在 lock 文件时，npm install 会遵循它。但 npm install 的设计初衷是“安装或更新依赖”，它有时仍会尝试更新 lock 文件（比如你手动修改了 package.json）。在追求绝对一致性的场景下，我们需要一个更严格、更纯粹的命令：npm ci。

ci 是 “Continuous Integration”（持续集成）的缩写，这个命令是专门为自动化环境和确保严格一致性而设计的。

1
2
3
4

# 添加生产依赖
npm install dayjs
# 添加开发依赖
npm install jest -D

4.5. 本章核心速查总结

4.6. 高频面试题与陷阱

第五章：包管理器选型指南——NPM、Yarn 与 PNPM 全方位对比

5.1. 历史视角：Yarn Classic 为何能挑战 NPM？

在 2016 年前，NPM (v3/v4) 作为唯一的官方包管理器，存在一些广为诟病的痛点，这为 Yarn 的诞生提供了契机。

• 痛点一：安装速度慢: NPM 采用串行方式下载和安装依赖，一个包必须等上一个包安装完成后才能开始，导致整体效率低下。
• 痛点二：依赖不确定 (v4 之前): 早期的 NPM 没有 lock 文件的概念，仅靠 package.json 的版本范围无法保证团队成员安装的依赖版本完全一致，是“在我这儿是好的啊”问题的重灾区。
• 痛点三：命令行输出混乱: 安装过程中的输出信息非常冗长，错误信息常常被淹没在大量的日志中。

正是在这个背景下，Facebook (现 Meta) 推出了 Yarn (Classic)，它像一位革命者，精准地解决了上述所有问题：

• 并行安装: Yarn 将依赖解析和下载过程并行化，极大地提升了安装速度。
• 引入 yarn.lock: Yarn 从诞生之初就带来了 lock 文件机制，保证了依赖的确定性，这也是后来 NPM v5+ 吸收 package-lock.json 的直接原因。
• 简洁的输出: Yarn 的命令行输出更加简洁、美观，关键信息一目了然。

Yarn 的出现，鲶鱼般地搅动了整个前端生态，迫使 NPM 团队开始正视并解决自身的问题。

5.2. 现代 NPM 的追赶与现状

面对 Yarn 的强力挑战，NPM 团队在 v5 版本后奋起直追：

• 引入 package-lock.json: 正式采纳了 lock 文件机制，解决了确定性问题。
• 优化缓存与性能: 引入了更完善的缓存机制，并对依赖解析算法进行了优化，使得安装速度有了显著提升。
• npx 命令: 引入了 npx，极大地简化了调用项目本地依赖和试用 NPM 包的流程。

如今的现代 NPM (v7+)，在功能和性能上已经基本追平了 Yarn Classic，成为了一个稳定、可靠的官方选择。但就在 NPM 和 Yarn 的“两强争霸”看似尘埃落定时，一位思想完全不同的“颠覆者”登场了。

5.3. PNPM 的“降维打击”：性能与磁盘空间的极致优化

PNPM (Performant NPM) 并没有在 NPM 和 Yarn 的赛道上进行微创新，而是从一个全新的维度——文件系统管理——对 node_modules 的实现方式发起了革命。

让我们通过一个真实的评测，来直观感受它的威力。我们将使用 create-vite 创建一个标准的 React + TypeScript 项目，然后分别用三者来安装依赖。

测试项目初始化:

1
2
3
4
5

npm install -g yarn
npm install -g pnpm

npm create vite@latest pnpm-vs-others -- --template react-ts
cd pnpm-vs-others

评测一：首次安装 (无缓存)

我们分别删除 node_modules 和 lock 文件，然后执行安装命令。

1
2

# 使用 NPM
npm install

1
added 268 packages in 25.3s

1
2

# 使用 Yarn
yarn

1
Done in 21.8s.

1
2

# 使用 PNPM
pnpm install

1
2
3
4
Packages: +268
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Progress: resolved 268, reused 0, downloaded 268, added 268, done
Done in 13.5s

评测二：二次安装 (有缓存)

我们再次删除 node_modules，但不删除 lock 文件，再次执行安装。

1
2

# 使用 PNPM (二次安装)
pnpm install

1
2
3
4
Packages: +268
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Progress: resolved 268, reused 268, downloaded 0, added 268, done
Done in 4.2s

评测三：磁盘空间占用

安装完成后，我们查看 node_modules 目录的大小（结果因系统和版本而异）。

• NPM/Yarn: node_modules 约 280 MB。
• PNPM: node_modules 约 180 MB（实际占用，但通过链接共享了全局文件）。

结论: 无论是在安装速度（尤其是二次安装）还是磁盘空间占用上，PNPM 都表现出了压倒性的优势。这背后的秘密，就在于它独特的 node_modules 管理机制。

5.4. 深入 PNPM 内核：非扁平化结构与符号链接

5.4.1. 幽灵依赖：NPM/Yarn 扁平化结构的副作用

为了解决早期 NPM 版本中因依赖层级过深导致 Windows 路径超长的问题，NPM v3+ 和 Yarn 都采用了“扁平化” 的 node_modules 结构。它们会尝试将所有依赖（包括子孙依赖）都提升到 node_modules 的根目录。

这种结构带来了一个严重的副作用——幽灵依赖。假设你的项目只依赖了 axios，而 axios 依赖了 follow-redirects。在扁平化结构下，follow-redirects 也会被提升到根目录。这意味着，你可以在你的代码中 require('follow-redirects')，即使你从未在 package.json 中声明过它！这是一种非常不规范、且极具风险的行为。

5.4.2. PNPM 的解决方案：链接与全局存储

PNPM 通过两个核心技术彻底解决了上述问题：

1. 内容寻址的全局存储:
   PNPM 会在你的主磁盘（如 C:\Users\YourUser\.pnpm-store）中创建一个全局仓库。任何版本的任何包，在你的电脑上 只会下载并实体存储一次。

2. **硬链接 与符号链接 **:

• 当你执行 pnpm install 时，PNPM 不会复制文件。它会通过 硬链接，将全局仓库中的包文件“映射”到你项目的 node_modules/.pnpm 目录中。硬链接几乎不占用额外的磁盘空间。
  * 然后，它会在 node_modules 根目录创建 符号链接（类似于快捷方式），指向 .pnpm 目录中对应的包。

这种结构带来了三大好处：

• 节省空间: 100 个项目依赖同一个版本的 react，在磁盘上也只存一份实体文件。
• 速度极快: 大部分依赖直接从全局仓库链接而来，省去了大量的下载和文件 I/O。
• 杜绝幽灵依赖: node_modules 根目录只会有你在 package.json 中明确声明的依赖的符号链接。axios 的依赖 follow-redirects 不会出现在根目录，你自然也无法在代码中非法引用它，保证了依赖关系的绝对纯洁。

5.5. 2025 年技术选型指南：我应该选择哪一个？

新项目 (个人或团队)
首选：PNPM

• 理由：极致的性能、巨大的磁盘空间节省、严格的依赖管理，它代表了当前包管理器的最佳实践和未来方向。其内置的 workspace 功能对 Monorepo 项目的支持也是一流的。

维护现有项目
原则：遵循项目已有规范

• 如果项目已在使用 NPM 和 package-lock.json：继续使用 NPM。现代 NPM 稳定且可靠，没有必要为了迁移而迁移。
• 如果项目已在使用 Yarn (尤其是 Yarn v2+ Berry 和 PnP 模式)：继续使用 Yarn。Yarn Berry 的 Plug’n’Play 特性提供了一种完全不同的、无 node_modules 的管理模式，有其独特的优势，应保持一致。

特定受限环境
备选：NPM

• 在某些严格的、无法创建符号链接的企业环境或 CI/CD 平台中，NPM 的传统 node_modules 结构可能是更稳妥的选择。

5.6. 本章核心速查总结

5.7. 高频面试题与陷阱

第六章：大型项目管理术——Monorepo 架构与 PNPM Workspaces 实战

6.1. 什么是 Monorepo？它与传统的 Multi-repo 有何不同？

在软件开发中，代码仓库的管理方式主要有两种：

• Multi-repo (多仓库): 这是最传统、最常见的方式。每个项目、每个库都有自己独立的 Git 仓库。例如，webapp 在一个仓库，ui-components 在另一个仓库。
• Monorepo (单体仓库): 将所有相关的项目、库都放在同一个 Git 仓库中进行管理。例如，webapp 和 ui-components 都在同一个仓库的不同子目录中。

这两种模式在工作流、代码共享、版本控制等方面有着天壤之别。

6.2. Monorepo 的优势：以“设计系统”为例

为了更具体地感受 Monorepo 的威力，让我们构思一个真实的企业级场景：Acme 公司要构建自己的设计系统。

这个系统至少包含三个包：

• @acme/ui-components: 核心的 UI 组件库 (React/Vue)。
• @acme/docs: 用于展示和测试组件的文档站 (VitePress/Storybook)。
• @acme/webapp: 使用这套组件库的官方主应用。

在 Multi-repo 模式下，工作流会是这样：

1. 修改了 @acme/ui-components 里的一个按钮组件。
2. 为了在文档站里看效果，需要先将组件库发布一个 beta 版本到 npm。
3. @acme/docs 项目更新依赖，安装这个 beta 版本，然后启动调试。
4. 调试通过后，再将组件库发布一个正式版。
5. @acme/webapp 和 @acme/docs 再更新到正式版。这个流程因为涉及多次发布和安装，效率极其低下。

而在 Monorepo 模式下，工作流将变得无比丝滑：

1. 直接在 Monorepo 中修改 @acme/ui-components 的按钮组件代码。
2. 由于 @acme/docs 是直接通过源码引用组件库的，它的开发服务器会 立即热更新，实时看到修改效果。
3. 调试完成后，进行 一次原子化提交，这个提交同时包含了组件库的修改和（可能有的）文档站的适配修改。

6.3. 实战入门：使用 PNPM Workspaces 搭建你的第一个 Monorepo

PNPM 内置了对 Monorepo（在 PNPM 中称为 Workspaces/工作区）的顶级支持。现在，让我们亲手搭建上面提到的 Acme 设计系统。

第一步：创建 Monorepo 根目录

1
2
3
4
5
6
7
8
9

# 创建并进入项目根目录
mkdir acme-design-system && cd acme-design-system

# 初始化根 package.json
pnpm init

在 package.json 的 下方加上 private: true 是 Monorepo 根目录的最佳实践，它表示这个包是私有的，不会被发布到公共仓库 。
  "packageManager": "pnpm@10.14.0",
  "private": true

第二步：定义工作区 (Workspace)

创建 pnpm-workspace.yaml 文件，这是声明此项目为 Monorepo 的“开关”。

文件路径: acme-design-system/pnpm-workspace.yaml

1
2
3

packages:
  # 我们约定，所有子项目都放在 'packages' 目录下
  - 'packages/*'

第三步：创建子项目

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

# 创建用于存放所有子项目的目录
mkdir packages

# 进入 packages 目录并创建三个子项目
cd packages
mkdir ui-components
mkdir docs
mkdir webapp
# 分别初始化每个子项目
cd ui-components && pnpm init && cd ..
cd docs && pnpm init && cd ..
cd webapp && pnpm init && cd ..

# 回到项目根目录
cd ..

此时，你的项目结构应该是这样：

1
2
3
4
5
6
7
8
9
10

# acme-design-system/
├── packages/
│   ├── docs/
│   │   └── package.json
│   ├── ui-components/
│   │   └── package.json
│   └── webapp/
│       └── package.json
├── package.json
└── pnpm-workspace.yaml

第四步：安装公共依赖

我们的三个子项目很可能都依赖 react 和 typescript。我们可以把这些公共依赖安装在 Monorepo 的 根目录，让所有子项目共享。

使用 -w 或 --workspace-root 标志来告诉 PNPM 在根目录安装。

1
2

# 在 Monorepo 根目录执行
pnpm add react react-dom typescript -D -w

执行后，react 等依赖会被安装到根目录的 node_modules 中，并被自动“提升”（hoist），所有子项目都可以直接引用到它们，无需重复安装。

6.4. 依赖管理与内部包的互相引用

这是 Monorepo 最神奇的地方：如何让 @acme/webapp 依赖本地的 @acme/ui-components？

第一步：修改子项目名称

为了能互相引用，我们需要先给子项目 package.json 里的 name 字段赋予规范的、带作用域的名称。

• packages/ui-components/package.json -> "name": "@acme/ui-components"
• packages/docs/package.json -> "name": "@acme/docs"
• packages/webapp/package.json -> "name": "@acme/webapp"

第二步：使用 workspace:* 协议

现在，我们编辑 webapp 的 package.json，让它依赖 ui-components：

文件路径: packages/webapp/package.json

1
2
3
4
5
6
7
8

{
  "name": "@acme/webapp",
  "version": "1.0.0",
  ...
  "dependencies": {
    "@acme/ui-components": "workspace:*"
  }
}

workspace:* 这个特殊的协议告诉 PNPM：“我依赖的 @acme/ui-components 不是 NPM 仓库里的某个版本，而是 当前工作区中的那个本地包”。

第三步：运行 pnpm install

在 Monorepo 根目录 运行：

1

pnpm install

PNPM 会识别到 workspace:* 协议，然后它不会去下载任何东西，而是会在 packages/webapp/node_modules 目录下，创建一个指向 packages/ui-components 目录的 符号链接。

第四步：在子项目中运行脚本

如果你想运行 webapp 的 dev 脚本，可以使用 -F 或 --filter 标志：

1
2

# 假设 webapp 的 package.json 中有 "dev": "vite"
pnpm --filter @acme/webapp dev

这个命令会精准地只运行指定子项目的脚本，是 Monorepo 开发中的日常操作。

6.5. 本章核心速查总结

6.6. 高频面试题与陷阱

第七章：揭秘“构建”过程——代码转换、打包与压缩

7.1. 我们的目标：让 weather-cli 跑在浏览器上

让我们从一个清晰的目标开始：将我们在前面章节中创建的多文件、使用 CommonJS (require) 语法的 weather-cli Node.js 项目，改造为一个 可以在浏览器 index.html 中引用的、单一的、优化过的 bundle.min.js 文件。

要达成这个目标，我们的源码必须经历一次“进化”，完成三个环节的转换

7.2. 环节一：代码转换

7.2.1. 理论解析

场景: 假设我们想用 ES2020 的新语法——可选链操作符 (?.) 来简化 weather-cli 的代码，以避免因数据结构层级过深而导致的运行时错误。

升级前 (安全但繁琐):

1
2

const cityInfo = response.data.cityInfo;
const city = cityInfo && cityInfo.city ? cityInfo.city : '未知';

升级后 (简洁但有兼容风险):

1

const city = response.data.cityInfo?.city || '未知';

这段简洁的代码，在旧版本的浏览器中会直接导致语法错误。为了解决这个问题，我们需要 Babel 这样的“代码翻译官”，将高版本的 JavaScript 语法，转换为功能等价、兼容性更好的旧版语法。

同时，对于新的 函数或方法（如 Array.prototype.flat()），我们还需要 Polyfill（垫片） 来在旧环境中“模拟”出这些 API。

7.2.2. 动手实践：配置并运行 Babel

第一步：安装 Babel 核心依赖

1

pnpm add @babel/core @babel/cli @babel/preset-env -D

• @babel/core: Babel 的核心引擎。
• @babel/cli: 提供了从命令行使用 Babel 的能力。
• @babel/preset-env: 一个智能的“预设包”，能根据目标环境自动确定需要转换哪些新语法。

第二步：配置 Babel
在项目根目录创建 babel.config.js 文件。
文件路径: weather-cli/babel.config.js

1
2
3
4
5
6
7
8
9
10
11
12
13

module.exports = {
    presets: [
      [
        '@babel/preset-env',
        {
          targets: { // 我们的目标浏览器
            "chrome": "88",
          },
          modules: "cjs", // 强制转换为 CommonJS 模块
        },
      ],
    ],
  }; 

第三步：组织源码并执行转译
为了规范，新建一个 src 目录，并将 index.js 移动进去。在 package.json 中添加 build:babel 脚本：

1
2
3

"scripts": {
  "build:babel": "babel src --out-dir dist"
}

babel src --out-dir dist 命令意为：将 src 目录下的所有 JS 文件进行转译，输出到 dist 目录。

执行它：

1

npm run build:babel

执行后，项目下会生成一个 dist 目录，里面的 .js 文件就是被 Babel 转换过后的兼容性代码。

7.3. 环节二：模块打包

7.3.1. 理论解析

经过 Babel 处理后，dist 目录里的代码虽然语法兼容了，但它们依然是两个独立的文件，并且保留着 require 和 module.exports 语句。浏览器既不认识这种模块语法，也无法接受我们让它发起多个 HTTP 请求去加载这些零散的文件。

打包器 的工作就是解决这个问题。它会从一个入口文件出发，分析 require 语句，绘制出一张“依赖图”，最终将所有必需的模块合并成一个浏览器可执行的大文件 bundle.js。

7.3.2. 动手实践：使用 Browserify 打包

第一步：安装 Browserify
Browserify 是一个专注于将 CommonJS 模块打包成浏览器代码的工具，非常适合我们当前的场景。

1

pnpm add browserify -D

第二步：添加打包脚本
在 package.json 的 scripts 中添加 build:bundle 脚本：

1
2
3
4

"scripts": {
  "build:babel": "babel src --out-dir dist",
  "build:bundle": "browserify dist/index.js --outfile bundle.js"
}

此命令意为：从 dist/index.js 入口开始，分析依赖，然后将它们全部打包进 bundle.js 文件。

执行它：

1

npm run build:bundle

执行后，项目根目录会生成一个 bundle.js 文件。这个文件已经包含了我们所有的代码，并且可以在浏览器中运行。

7.4. 环节三：代码压缩

7.4.1. 理论解析

我们的 bundle.js 文件虽然功能完备，但其中包含了大量的空格、换行和注释，体积较大，会影响线上用户的加载速度。代码压缩 (Minification) 就是构建流程中必不可少的“瘦身”工序。

压缩前:

1
2
3
4
5

// 获取城市代码，如果找不到则返回默认值
function getCityCode(city) {
  const cityMap = require('./cities.js');
  return cityMap[city] || '101281001'; // 默认潮州
}

压缩后:

1

function getCityCode(c){return require("./cities.js")[c]||"101281001"}

7.4.2. 动手实践：使用 Terser 压缩

第一步：安装 Terser
Terser 是一个高效的 JavaScript 压缩器。

1

pnpm add terser -D

第二步：添加压缩脚本
在 package.json 中添加 build:minify 脚本：

1
2
3
4
5

"scripts": {
  "build:babel": "babel src --out-dir dist",
  "build:bundle": "browserify dist/index.js --outfile bundle.js",
  "build:minify": "terser bundle.js --output bundle.min.js --compress --mangle"
}

此命令意为：读取 bundle.js，进行压缩和变量名混淆，然后输出到 bundle.min.js 文件。

执行它：

1

npm run build:minify

现在，你得到了最终的产物：bundle.min.js。

最后一步：在浏览器中验证
创建一个 index.html 文件来加载我们亲手构建出的 bundle.min.js。
文件路径: weather-cli/index.html

1
2
3
4
5
6
7
8
9
10

<!DOCTYPE html>
<html>
<head>
  <title>Weather App</title>
</head>
<body>
  <h1>查看浏览器控制台输出</h1>
  <script src="./bundle.min.js"></script>
</body>
</html>

用浏览器打开这个 index.html 文件，然后打开开发者工具的控制台（按 F12），你将看到 weather-cli 成功打印出了天气信息！

7.5. 本章核心速查总结

7.6. 高频面试题与陷阱

第八章：一个时代的印记——回溯 Webpack，理解下一代构建工具的基石

8.1. 混沌初开：Webpack 诞生前的“前端江湖”

在 Webpack 出现之前，前端开发更像是一门“手艺活”，充满了刀耕火种式的原始操作。

• 刀耕火种的年代: 开发者通过 <script> 标签手动管理 JavaScript 文件的依赖顺序。一个复杂的页面可能会有几十个 <script> 标签。这种“人肉运维”模式，极易因顺序错误导致“依赖地狱”，同时所有变量都暴露在全局作用域下，造成严重的变量污染。

• 社区的早期探索: 为了解决这些问题，社区涌现出了一批先行者：

  • 任务流工具 (Task Runner): 以 Grunt 和 Gulp 为代表，它们可以自动化地执行一系列任务，如压缩代码、合并文件、编译 CSS。但它们关心的是“流程”，而非代码之间的“依赖关系”。
  • 模块化加载器 (Module Loader): 以 RequireJS 和 Sea.js 为代表，它们在浏览器端实现了模块化加载，解决了依赖管理和全局污染问题。但它们并未在“构建时”将模块打包，导致线上依然存在大量零散的 HTTP 请求。
  • 破局者 Browserify: 它是现代打包工具思想的雏形。Browserify 创新地将 Node.js 的 CommonJS 模块规范引入了前端，让开发者能使用 require 来组织代码，并通过构建命令将所有依赖打包成一个文件。然而，它天生只为处理 JavaScript 而生，对于 CSS、图片等非 JS 资源的处理能力非常有限。

整个前端江湖，迫切地需要一个能统一管理所有类型资源、并深刻理解模块化依赖的终极解决方案。

8.2. Webpack 的“思想革命”：一切皆模块

Webpack 的登场，带来的不仅是一个工具，更是一种颠覆性的哲学——一切皆模块。

在 Webpack 的世界里，不再区分 JavaScript、CSS、图片、字体…… 开发者看到的 所有静态资源，都可以被视为“模块”，并能像 import 一个 JS 文件一样，被纳入到一个统一的 依赖图 中。

为了实现这一宏伟思想，Webpack 设计了两大核心基石：

• Loader (加载器): 可以将其比喻为“翻译官”。Webpack 本身只理解 JavaScript 和 JSON 文件。当它在 import 语句中遇到它不认识的“语言”（如 .scss, .vue, .jsx 文件，甚至是一张图片）时，Loader 就负责登场，将其“翻译”成 Webpack 能理解的有效模块（通常是 JavaScript 字符串或文件路径）。

• Plugin (插件): 可以将其比喻为“架构师”。如果说 Loader 的工作是“点对点”的文件转换，那么 Plugin 则拥有更广阔的视野。它能“钩入(Hook)”到打包过程的各个生命周期节点，执行更复杂的任务，如打包优化、资源管理、环境变量注入等。我们所熟知的 HtmlWebpackPlugin（自动生成 HTML 文件并注入打包好的 JS）和 DefinePlugin（定义全局常量）都是强大的插件。

8.3. 登峰造极：Webpack 如何统治前端工程化

随着 React, Vue, Angular 等现代框架的兴起，复杂的单页应用（SPA）成为主流。这类应用对 代码分割、懒加载、Tree Shaking 等高级功能的需求激增，而 Webpack 在这些领域几乎没有对手，迅速成为各大框架脚手架（如 create-react-app, vue-cli）的内置核心，开启了它的统治时代。

• Code Splitting (代码分割): 对于大型 SPA，将所有代码打包成一个文件是灾难性的。Webpack 允许我们通过动态导入语法 import()，将代码分割成多个“块”(chunks)，只在需要时才去网络加载，极大地优化了应用的首屏性能。

  1 2 3 4 5 6

  // 点击按钮后，才去加载 login-modal.js 这个模块 loginButton.addEventListener('click', () => { import('./components/login-modal.js').then(module => { module.showLoginModal(); }); });

• Tree Shaking (摇树优化): 正如我们在上一章所学，Webpack 能通过静态分析 ES Module 的 import/export，在打包时移除所有未被引用的“死代码”，进一步减小打包体积。

• 无与伦比的生态系统: Webpack 社区极其繁荣。无论是最新的 CSS 预处理器、前沿的 JS 语法，还是各类资源的优化，你几乎总能找到一个成熟的 Loader 或 Plugin 来解决问题。

8.4. “成也萧何，败也萧何”：Webpack 的“痛点”与性能瓶颈

Webpack 的强大，源于它“一切皆打包”的核心工作模式。然而，这也正是其“笨重”的根源。

8.4.1. “打包”带来的原罪：缓慢的开发服务器

Webpack Dev Server 的工作原理是：

1. 启动时预打包: 在启动时，它必须先从入口文件出发，遍历整个项目的依赖，构建完整的依赖图，然后将它们全部打包成 bundle。
2. 存入内存: 打包完成后，它并不会将文件写入磁盘，而是存放在内存中，以便快速提供给浏览器。

这个“先打包，再启动”的模式，导致项目越大、依赖越复杂，Starting the development server... 的等待时间就越长。一杯咖啡的时间，可能就耗在了等待项目启动上。

虽然 Webpack 的热模块替换（HMR）是革命性的，但它的更新速度依然受限于“重新打包”的速度。一个文件的改动，可能会触发一连串模块的重新构建，导致更新延迟。

8.4.2. 配置的“迷宫”：陡峭的学习曲线

Webpack 的极高灵活性和庞大生态，也带来了极其复杂的配置。这也是“前端配置工程师”这一戏称的由来。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46

const path = require('path');
const HtmlWebpackPlugin = require('html-webpack-plugin');
const MiniCssExtractPlugin = require('mini-css-extract-plugin');

module.exports = (env, argv) => {
  const isProd = argv.mode === 'production';

  return {
    entry: './src/index.js',
    output: {
      path: path.resolve(__dirname, 'dist'),
      filename: 'bundle.[contenthash].js',
      clean: true,
    },
    module: {
      rules: [
        {
          test: /\.m?js$/,
          exclude: /node_modules/,
          use: {
            loader: 'babel-loader',
            options: { presets: ['@babel/preset-env', '@babel/preset-react'] }
          }
        },
        {
          test: /\.scss$/i,
          use: [
            isProd ? MiniCssExtractPlugin.loader : 'style-loader',
            'css-loader',
            'postcss-loader',
            'sass-loader',
          ],
        },
      ],
    },
    plugins: [
      new HtmlWebpackPlugin({ template: './public/index.html' }),
      isProd ? new MiniCssExtractPlugin({ filename: 'styles.[contenthash].css' }) : undefined,
    ].filter(Boolean),
    devServer: {
      static: './dist',
      hot: true,
    },
    //... and more
  };
};

要正确写出这样的配置，开发者需要理解 entry, output, rules, loader, plugin, mode 等众多概念及其协同工作的方式，配置成本和心智负担非常高。

8.5. 时代的回响：Webpack 留下的宝贵遗产与未来的方向

• Webpack 并非过去式: 必须强调，Webpack 5 在性能（如持久化缓存）和配置易用性上做出了巨大改进。在许多大型、成熟的生产环境中，它的稳定性和强大的生态依然是首选。

• 为后浪铺路: Webpack 沉淀下的核心思想，已被所有现代构建工具继承：

  • 依赖图谱分析
  • Loader/Plugin 架构思想
  • 代码分割与 Tree Shaking 理念
  • HMR 机制

• 新时代的破局点: 下一代工具的革命性突破，源于两大技术奇点的成熟：

  1. 浏览器原生支持 ES Module (ESM): 这是 Vite 等工具实现“闪电般”冷启动的 根本基石。开发时，构建工具可以跳过“打包”这一步，直接让浏览器按需去请求各个模块文件。
  2. 编译型语言的降维打击: 以 Go 语言编写的 esbuild 和 Rust 语言编写的 SWC，在编译、压缩等任务上，比基于 Node.js 的传统工具快上 数十甚至上百倍。

第九章：新时代的引擎轰鸣——Vite 全面精通

9.1. 范式转移：从“先打包，再启动”到“即时服务”

9.1.1. 亲身体验：“魔法”是如何发生的

在深入理论之前，让我们先用一分钟时间，亲手见证 Vite 的“魔法”。

动手实践：请打开您的终端，执行以下命令来创建一个全新的 Vite 项目。

1
2

# 我们使用 pnpm，速度更快
pnpm create vite

在交互式问答中，你可以为项目命名（如 vite-magic-show），并选择 Vanilla -> TypeScript 模板。这是一个不依赖任何框架的、纯净的 TypeScript 项目。

1
2
3
4
5
6

# 进入项目目录
cd vite-magic-show
# 安装依赖
pnpm install
# 启动开发服务器
pnpm dev

1
2
3
4
5
6

VITE v5.3.1  ready in 312 ms

➜  Local:   http://localhost:5173/
➜  Network: use --host to expose
➜  press h + enter to show help

请注意这个时间：ready in 312 ms。Vite 几乎是瞬间就启动了服务。现在，用浏览器打开 http://localhost:5173/。

接下来，找到并打开 src/main.ts 文件，随意修改其中的内容，例如：

1
2
3
4

// src/main.ts
document.querySelector<HTMLDivElement>('#app')!.innerHTML = `
  <h1>Hello Prorise! Vite is amazing!</h1>
`

当您按下 Ctrl + S 保存的瞬间，浏览器中的页面几乎是 同步更新 的，没有任何可感知的延迟。

这就是 Vite 带来的第一个震撼：告别漫长的启动和更新等待，沉浸在 极致的心流开发体验 之中。

9.1.2. 根本原因剖析：两种模式的对决

这“魔法”的背后，是 Vite 和 Webpack 在底层工作模式上的 范式转移。

• Webpack 的“预打包”模式:
  回顾第八章，Webpack 在启动开发服务器时，必须从入口文件开始，遍历整个项目的依赖，构建一个完整的依赖图，然后将所有模块打包（Bundle）进内存。项目越大，这张图越复杂，启动前的“打包”耗时就越长，从而导致了漫长的“咖啡时间”。

• Vite 的“按需服务”模式:
  Vite 则彻底颠覆了这个流程。它利用了现代浏览器原生支持的 ES Module (ESM) 语法。

  1. 启动时：Vite 仅启动一个轻量级的 Web 服务器，几乎是零开销。它 不需要进行任何打包操作。
  2. 浏览器请求：当浏览器加载 index.html 并解析到 <script type="module" src="/src/main.ts"></script> 时，它会主动向 Vite 服务器发起一个对 /src/main.ts 的 HTTP 请求。
  3. Vite 响应：Vite 服务器接收到请求，对 /src/main.ts 这个 单个文件 进行即时编译（例如将 TypeScript 转换为 JavaScript），然后直接返回给浏览器。
  4. 循环：如果 main.ts 文件内部又有 import 了其他模块，浏览器会继续发起新的 HTTP 请求，Vite 也继续按需编译并返回。

在这个模式下，浏览器自身成为了“打包器”，它负责根据 import 语句来请求和组织模块。Vite 则退居为一个高效的、按需服务的“文件翻译官”。因此，项目的规模与启动时间彻底解耦，实现了恒定的、毫秒级的启动速度。

9.1.3. 热更新的“质变”

这种模式同样让 热模块替换 (HMR) 发生了质变。

• Webpack HMR: 当你修改一个模块时，Webpack 需要找出这个模块所属的 chunk（代码块），并重新计算和构建这整个 chunk，即使其中很多模块并未改变。
• Vite HMR: 当你修改一个模块（如 utils.ts）时，Vite 能利用 ESM 清晰的模块边界，精准地知道只有这一个模块失效了。它通过 WebSocket 通知浏览器：“嘿，utils.ts 更新了，请重新请求它。” 浏览器接收到指令后，只会重新请求这一个文件，并凭借其原生的 ESM 处理能力，无缝地替换掉旧模块，而无需刷新整个页面或重新加载大量不相关的代码。

9.2. Vite 的“双核引擎”：深入理解开发与生产模式的差异

Vite 的设计哲学中，最核心的一点就是 区分开发与生产。它认为，开发阶段我们最追求的是 极致的响应速度和调试体验，而生产阶段我们最追求的是 最优的加载性能和兼容性。为了同时达到这两个目标，Vite 创造性地采用了一套“双核引擎”架构。

9.2.1. 开发环境的“王牌”：原生 ESM + esbuild

我们在上一节体验的“即时服务”魔法，其背后的两大功臣，就是 浏览器原生 ESM 支持 和 esbuild。

在这个工作流中，esbuild 扮演着至关重要的角色。

• esbuild 是什么？
  它是一个使用 Go 语言编写的、速度极快的 JavaScript Bundler / Transpiler / Minifier。由于 Go 语言是编译型语言，并且能充分利用多核 CPU 进行并行处理，esbuild 在执行代码转换任务时，比用 JavaScript 编写的传统工具（如 Babel, Terser）快 10-100 倍。

• esbuild 在 Vite 开发环境中的角色：在开发阶段，Vite 并不使用 esbuild 来“打包”，而是主要利用其 闪电般的“转译”能力。当浏览器请求一个 main.ts 文件时，Vite 会在瞬间调用 esbuild 将 TypeScript 代码转换为 JavaScript，然后返回给浏览器。对于 .jsx 或 .tsx 文件也是同理。

9.2.2. 生产环境的“守护神”：Rollup

一个核心疑问随之而来：既然开发时可以不打包，为什么执行 pnpm build 进行生产部署时，Vite 还是要打包呢？

这是因为直接将成百上千个未经优化的模块部署到线上，会带来严重的性能问题。Vite 在生产环境构建时，选择了一个久经考验、极其成熟的打包器——Rollup 来完成这项任务。

生产环境仍需打包的四大理由：

1. 网络性能: 即使有 HTTP/2，同时发起成百上千个模块的 HTTP 请求也会在浏览器和服务器端造成巨大的网络开销和拥堵，形成“请求瀑布流”，严重拖慢页面加载速度。打包能将这些请求合并为少数几个。
2. 更优的 Tree Shaking: Rollup 是最早普及 Tree Shaking 概念的打包器之一，它基于 ESM 的静态分析能实现非常彻底的死代码消除，确保最终产物中不包含任何一行无用代码，这是单纯的浏览器 ESM 加载无法做到的。
3. 代码分割: Rollup 能进行智能的代码分割，将应用代码拆分成多个按需加载的块（chunks），进一步优化首屏加载性能。
4. 统一优化与兼容: 打包过程可以统一进行代码压缩、混淆、以及通过插件（如 Babel）处理对旧版浏览器的兼容性问题，确保最终代码在各种环境下的健壮性。

为什么选择 Rollup？
Rollup 由 Vue 的作者尤雨溪（也是 Vite 的作者）长期使用和贡献，它打包输出的 ES Module 格式代码非常“干净”，副作用少，是开发 JS 库的首选。Vite 沿用其成熟的打包能力和庞大的插件生态，来为生产环境的最终产物保驾护航，是一个非常明智的选择。

9.3. “秘密武器”：依赖预构建全解析

我们在 9.1 节中建立的核心认知是：Vite 开发服务器通过按需服务源码文件来避免“打包”。然而，这个原则有一个重要的例外：它 不适用 于 node_modules 里的 第三方依赖。

Vite 会在首次启动时，花费少量时间对第三方依赖进行“预构建”，这是一个极其聪明的优化策略，旨在解决两大痛点。

9.3.1. 它要解决的两大痛点

1. 模块格式兼容：将 CommonJS (CJS) 统一为 ES Module (ESM)

尽管我们正在全面拥抱 ES Module，但 node_modules 中依然有大量以 CommonJS 格式发布的历史悠久的优秀库（例如 react 的部分依赖）。浏览器本身 完全不认识 CommonJS 的 require() 和 module.exports 语法。如果不进行处理，浏览器在请求这些模块时会直接报错。

解决方案: Vite 使用 esbuild 扫描 node_modules，找到所有 CommonJS 格式的依赖，并将它们强制转换为浏览器友好的 ES Module 格式。

2. 性能瓶颈：避免“请求瀑布流”

一些现代库虽然以 ESM 格式发布，但其内部可能由成百上千个细碎的模块文件组成（一个典型的例子是 lodash-es）。

场景: 假设你在代码中 import { debounce } from 'lodash-es'。debounce 函数本身可能又 import 了其他十几个内部工具函数。如果 Vite 对这些内部 import 也进行“按需服务”，浏览器为了加载一个小小的 debounce 功能，就可能需要同时发起数十个甚至上百个 HTTP 请求。这种“请求瀑布流”会严重阻塞浏览器渲染，让开发体验变得卡顿。

解决方案: 预构建再次使用 esbuild，将这些由许多小文件组成的 ESM 依赖 打包 成一个或少数几个大的 ESM 文件。这样，当浏览器请求 lodash-es 时，只需要一次 HTTP 请求就能获取全部所需代码。

9.3.2. 工作原理与缓存揭秘

依赖预构建的流程如下：

1. 扫描: Vite 启动后，会首先扫描你源码中所有的 import 和 require 语句，找出所有指向 node_modules 的“裸模块导入”。
2. 打包: 它将找到的所有第三方依赖作为入口，调用 esbuild 将它们打包成符合浏览器标准的 ESM 文件。
3. 缓存: 打包产物被存放在项目根目录的 node_modules/.vite/deps 目录下。每个预构建的依赖都会生成一个 JS 文件，以及一个记录元信息的 _metadata.json 文件。
4. 重写: Vite 会重写你的 import 路径。例如，你代码中的 import React from 'react' 会被重写为 import React from '/node_modules/.vite/deps/react.js?v=xxxx'，从而精确地指向缓存文件。

后续，只要依赖关系没有变化，Vite 每次启动都会直接使用这份缓存，这也是即使是大型项目，Vite 第二次及以后的启动也能“秒开”的核心原因。

9.3.3. 触发时机与强制重建

预构建 不会 在每次启动时都运行。它只在以下情况被触发：

• 首次启动开发服务器时。
• 当 package.json、lock 文件或 vite.config.ts 中的依赖相关配置发生变化后。

在某些特殊情况下，例如你手动修改了 node_modules 里的某个文件进行调试，或者缓存出现了问题，你可能需要 手动强制重建 依赖缓存。这可以通过在启动命令后添加 --force 标志来实现。

1
2

# 强制 Vite 重新进行依赖预构建
pnpm dev --force

1
2
3
4
5
6
Forced re-optimization of dependencies

  VITE v5.3.1  ready in 2854 ms

  ➜  Local:   http://localhost:5173/
  ...

你会发现，添加 --force 后，启动时间会回到首次启动时的秒级水平，因为 Vite 重新执行了完整的预构建流程。

9.4. 指挥中心：vite.config.ts 实战精解

Vite 奉行“约定优于配置”的原则，在零配置下就已经非常强大。但对于一个严肃的项目，自定义配置是必不可少的。我们可以在项目根目录下创建一个 vite.config.ts 文件来对 Vite 进行配置。

基础配置结构:
文件路径: vite-magic-show/vite.config.ts

1
2
3
4
5
6

import { defineConfig } from 'vite';

// defineConfig 工具函数提供了类型提示
export default defineConfig({
  // 在这里添加你的配置
});

9.4.1. 核心配置与环境变量

• root: 指定项目根目录（index.html 所在的位置），默认为 process.cwd()。
• base: 开发或生产环境下的公共基础路径。例如，如果你的应用部署在 https://prorise.com/app/ 下，那么 base 应设置为 '/app/'。
• mode: 模式，默认为 'development'（dev 命令）或 'production'（build 命令）。
• define: 定义全局常量替换。在开发时是全局变量，构建时是静态替换。例如 define: { __APP_VERSION__: JSON.stringify('1.0.0') }。
• envDir: 用于加载 .env 文件的目录，默认为根目录。

实战：配置部署路径和注入构建信息

问题场景: 我们的项目需要部署到服务器的 /my-app/ 子目录下。同时，我们希望在应用中可以展示当前的版本号和构建时间。

解决方案: 使用 base 和 define 选项。

文件路径: vite.config.ts

1
2
3
4
5
6
7
8
9
10
11
12
13
14

import { defineConfig } from 'vite';

export default defineConfig({
  // 1. 设置部署的基础路径
  base: '/my-app/',

  // 2. 定义全局常量
  define: {
    // __APP_VERSION__ 是一个自定义的常量，在代码中可以直接使用
    __APP_VERSION__: JSON.stringify('1.0.5'),
    // 注入构建时的时间戳
    __BUILD_DATE__: `"${new Date().toLocaleString()}"`
  }
});

在代码中使用:
文件路径: src/main.ts

1
2
3
4
5
6

console.log(`App Version: ${__APP_VERSION__}`);
console.log(`Build Date: ${__BUILD_DATE__}`);

// 运行时会输出：
// App Version: 1.0.5
// Build Date: "8/25/2025, 10:30:00 AM" (示例)

实战：管理环境变量
在真实项目中，API 地址、密钥等信息在开发和生产环境通常是不同的。Vite 通过 .env 文件对此提供了顶级支持。

1. 在项目根目录创建两个文件：
   文件路径: .env.development

   1 2	# 开发环境 API 地址 VITE_API_URL=http://localhost:8080/api/v1

   文件路径: .env.production

   1 2	# 生产环境 API 地址 VITE_API_URL=https://api.prorise.com/api/v1

   重要约定：为了安全，Vite 只会暴露以 VITE_ 为前缀的变量给客户端代码。

2. 在你的源码中访问这些变量：
   文件路径: src/api.ts

   1 2 3 4 5

   const API_URL = import.meta.env.VITE_API_URL; export function fetchUserData() { return fetch(`${API_URL}/users`); }

   当你运行 pnpm dev 时，API_URL 的值是 http://localhost:8080/api/v1；当你运行 pnpm build 时，打包出的代码中 API_URL 的值会自动变为 https://api.prorise.com/api/v1。

9.4.2. 开发服务器 (server)

这是用于配置 Vite Dev Server 的选项。

• host: 指定服务器主机名，默认为 'localhost'。
• port: 指定服务器端口，默认为 5173。
• open: 在服务器启动时自动在浏览器中打开应用。
• proxy: (极其常用) 配置自定义请求代理，解决开发时的跨域问题。

实战：配置 API 代理解决跨域
问题场景: 你的前端应用运行在 http://localhost:5173，但需要调用的后端 API 运行在 http://localhost:8080。由于浏览器的同源策略，直接请求会触发 CORS 跨域错误。

解决方案: 在 vite.config.ts 中配置 proxy，让 Vite Dev Server 帮你转发请求。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

import { defineConfig } from 'vite';

// defineConfig 工具函数提供了类型提示
export default defineConfig({
    server: {
        proxy: {
            // 字符串简写写法
            // '/foo': 'http://localhost: 4567',
            '/api': {
                target: "http://localhost:8080",
                changeOrigin: true,
                // 因为前端请求地址加了/api 前缀用于区分或触发代理，而后端实际接口路径没有这个前缀，通过 rewrite 去掉前缀才能让后端正确接收请求 。
                rewrite: (path) => path.replace(/^\/api/, '')
            }
        }
    }
});

配置完成后，你在代码中发起的 fetch('/api/users') 请求，实际上会被 Vite 服务器转发到 http://localhost:8080/users，从而完美绕开了浏览器的跨域限制。

9.4.3. 构建配置 (build)

这些选项用于控制生产环境的构建过程 (pnpm build)。

• outDir: 指定输出路径，默认为 dist。
• assetsDir: 指定生成静态资源的存放路径，默认为 assets。
• sourcemap: 是否生成 source map 文件。true 或 'inline'。开启后便于线上代码调试。
• minify: 指定使用哪种混淆器，默认为 'esbuild'（速度极快）。设为 false 可禁用混淆。
• rollupOptions: 传递给 Rollup 的高级选项，用于更精细的构建控制。

实战：优化生产环境的打包输出
问题场景: 我们希望将最终打包的文件输出到 prod-dist 目录，并为了方便管理，将 JS、CSS 和图片等资源分别存放到不同的子文件夹中。同时，为了线上调试，我们希望生成独立的 source map 文件。

解决方案: 配置 build 选项，特别是 rollupOptions。

文件路径: vite.config.ts

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

import { defineConfig } from 'vite';

export default defineConfig({
  build: {
    // 1. 指定输出目录
    outDir: 'prod-dist',
    // 2. 生成独立的 source map 文件
    sourcemap: true,
    // 3. 使用 rollupOptions 自定义输出文件结构
    rollupOptions: {
      output: {
        // [name]：文件名（不含扩展名）
        // [hash]：基于文件内容的哈希值
        // [ext]：文件扩展名
        chunkFileNames: 'static/js/[name]-[hash].js',
        entryFileNames: 'static/js/[name]-[hash].js',
        assetFileNames: 'static/[ext]/[name]-[hash].[ext]',
      }
    }
  }
});

执行 pnpm build 后，你的 prod-dist 目录结构会像这样：

1
2
3
4
5
6
7
8
9
10
11

prod-dist/
├── static/
│   ├── js/
│   │   ├── index-a1b2c3d4.js
│   │   └── vendor-e5f6g7h8.js
│   ├── css/
│   │   └── index-i9j0k1l2.css
│   └── img/
│       └── logo-m3n4o5p6.png
├── index.html
└── index-a1b2c3d4.js.map // Source map 文件

9.4.4. 解析 (resolve)

用于配置模块的解析行为。

• alias: (极其常用) 配置路径别名。

实战：配置 @ 路径别名
问题场景: 在深层嵌套的组件中，你可能需要写这样的导入语句：import { Button } from '../../../components/Button'，这种相对路径既不美观也难以维护。

解决方案: 配置 alias，让 @ 符号直接指向 src 目录。

准备工作: 为了在 vite.config.ts 中正确使用 Node.js 的内置模块（如 path）并获得类型提示，你需要安装它的类型定义文件。这是一个开发依赖，因为它只在开发阶段需要。

请在你的项目终端中运行以下命令：

1
2
3
4
5
6
7
8

# 使用 pnpm
pnpm add -D @types/node

# 或使用 npm
npm install -D @types/node

# 或使用 yarn
yarn add -D @types/node

安装完成后，现在可以修改配置文件了。

文件路径: vite.config.ts

1
2
3
4
5
6
7
8
9
10
11
12

import { defineConfig } from 'vite';
import path from 'path'; // 现在 TypeScript 可以正确识别 'path' 模块了

export default defineConfig({
  // ... 其他配置
  resolve: {
    alias: {
      // 设置 '@' 指向 'src' 目录
      '@': path.resolve(__dirname, './src'),
    }
  }
});

配置完成后，你就可以在任何地方使用清爽的绝对路径导入了：

1
2
3
4
5
6
7

// 之前: import { Button } from '../../../components/Button';
// 现在:
import { Button } from '@/components/Button';

// 之前: import { fetchUserData } from '../../api';
// 现在:
import { fetchUserData } from '@/api';

这极大地提升了代码的可读性和项目维护性。

9.5. 一等公民：Vite 中的 CSS 工程化方案

在前端工程化中，对 CSS 的管理始终是一个复杂但至关重要的环节。Webpack 通过一套复杂的 Loader 链条（style-loader, css-loader, postcss-loader, sass-loader 等）来处理样式，而 Vite 则将 CSS 视为项目中的“一等公民”，提供了开箱即用的、功能强大的工程化方案。

9.5.1. 开箱即用的体验

让我们回想一下在 Webpack 中处理 SCSS 文件需要做的配置：

1
2
3
4
5
6
7
8
9
10
11
12

// webpack.config.js (示例)
module.exports = {
  //...
  module: {
    rules: [
      {
        test: /\.scss$/i,
        use: ['style-loader', 'css-loader', 'sass-loader'],
      },
    ],
  },
};

你需要安装三个独立的 loader，并正确配置它们的顺序。

而在 Vite 中，你所需要做的仅仅是：

1. 安装相应的预处理器：

   1	pnpm add -D sass

2. 在你的组件中直接引入 .scss 文件：
   文件路径: src/main.ts

   1	import './styles/main.scss';

然后，它就直接工作了。 Vite 会自动检测文件扩展名，并调用已安装的相应预处理器进行处理，无需任何额外配置。这种零配置的体验，极大地降低了项目初始化的复杂度。

9.5.2. 实战技巧

Vite 不仅提供了基础支持，还内置了多种能显著提升开发效率的实战技巧。

1. @import 路径别名解析

在 9.4.4 节中，我们已经配置了 @ 指向 src 目录的路径别名。这个别名同样可以在 CSS 文件中无缝使用。

文件路径: src/components/Header.scss

1
2
3
4
5
6
7

// 无需再使用 ../../ 这样的相对路径
@import '@/styles/variables.scss';

.header {
  color: $primary-color;
  background-color: $background-color;
}

这使得样式文件的维护性和可移植性大大增强。

2. 将 CSS 作为字符串导入 (?inline)

在某些特殊场景下，你可能需要获取 CSS 的内容作为字符串，而不是直接将其注入到页面中（例如，在 Web Components 的 Shadow DOM 中动态创建 <style> 标签）。Vite 通过 ?inline 后缀提供了这个能力。

文件路径: src/components/MyComponent.ts

1
2
3
4
5
6
7
8
9

import cssString from './MyComponent.scss?inline';

// cssString 的值就是 MyComponent.scss 文件的内容
// => ".my-component { color: red; }"

// 你可以将其用于任何需要 CSS 文本的场景
const styleElement = document.createElement('style');
styleElement.innerHTML = cssString;
shadowRoot.appendChild(styleElement);

3. CSS Modules：实现组件级样式隔离

问题场景: 在大型项目中，不同组件的 CSS 类名很容易发生冲突。你在 Header.css 中定义的 .title 样式，可能会意外地污染到 Footer.css 中的 .title 样式。

解决方案: 使用 CSS Modules。Vite 对此提供了顶级的支持。只需将你的样式文件命名为 *.module.css (或 .module.scss 等)。

文件路径: src/components/Button.module.scss

1
2
3
4
5
6
7
8
9

// 定义一个局部作用域的类
.button {
  background-color: blue;
  border-radius: 8px;

  &:hover {
    background-color: darkblue;
  }
}

在组件中这样使用它：
文件路径: src/components/Button.ts

1
2
3
4
5
6
7
8
9
10

import styles from './Button.module.scss';

export function createButton(text: string) {
  const btn = document.createElement('button');
  // styles 对象包含了所有类名，其值是经过哈希处理后的唯一字符串
  // 例如 styles.button 的值可能是 "Button_button_a1B2c"
  btn.className = styles.button; 
  btn.innerText = text;
  return btn;
}

4. 全局注入 SCSS/Less 变量

问题场景: 你的项目中有一个 _variables.scss 文件，定义了所有的主题颜色、字体大小等。你希望在 所有 的 .scss 文件中都能直接使用这些变量，而不想在每个文件的开头都手动写一遍 @import '@/styles/_variables.scss';。

解决方案: 使用 css.preprocessorOptions 配置。

文件路径: vite.config.ts

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

import { defineConfig } from 'vite';
import path from 'path';

export default defineConfig({
  // ... 其他配置
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src'),
    }
  },
  css: {
    preprocessorOptions: {
      scss: {
        // 全局注入变量文件
        additionalData: `@import "@/styles/_variables.scss";`
      }
    }
  }
});

完成这个配置后，Vite 在编译任何 .scss 文件之前，都会自动在文件内容的 最前面 注入 @import "@/styles/_variables.scss"; 这行代码。现在，你可以在项目的任何一个 .scss 文件中直接使用 $primary-color 等全局变量了，极大地提升了主题管理的便利性。

9.5.3. PostCSS：CSS 的“Babel”

在我们深入 Vite 更多高级 CSS 功能之前，必须先认识一个在幕后默默工作的“大功臣”——PostCSS。当你看到像 Tailwind CSS 或 DaisyUI 这样神奇的 CSS 框架时，驱动它们的核心技术之一就是 PostCSS。

为了理解 PostCSS，最好的方式是将它与我们已经熟悉的 Babel 进行类比：

• Babel：接收我们写的 JavaScript 代码，将其解析成一种通用的数据结构（AST），然后通过各种插件（如 preset-env）对这个结构进行修改（比如将箭头函数转为普通函数），最后再把这个结构转换回浏览器兼容的 JavaScript 代码。
• PostCSS：做着完全一样的事情，但 处理的对象是 CSS。它接收我们写的 CSS 代码，将其解析成 AST（抽象语法树），然后通过各种插件（如 autoprefixer）对这个结构进行修改（比如添加浏览器厂商前缀），最后再转换回标准的 CSS 代码。

PostCSS 的威力体现在其强大的插件生态上，最著名的两个例子是：

1. autoprefixer: 这是最经典的 PostCSS 插件。它会自动读取 Can I Use 网站的数据，为你的 CSS 规则（如 display: grid）自动添加所需的浏览器厂商前缀（如 -ms-grid），让你从兼容性的琐事中解放出来。
2. tailwindcss: Tailwind CSS 框架本身就是一个 PostCSS 插件。它会在构建时，扫描你的 html 和 .js/.ts 文件，找到所有原子化类名（如 text-center, p-4），然后动态地生成你所需要的全部 CSS。

在 Vite 中使用 PostCSS
Vite 对 PostCSS 提供了开箱即用的支持。你无需进行任何配置，Vite 就会自动处理项目中的 PostCSS 配置。

实战：为项目添加 autoprefixer

第一步：安装依赖

1

pnpm add -D postcss autoprefixer

第二步：创建 PostCSS 配置文件
在项目根目录创建 postcss.config.js 文件。Vite 会自动识别并加载它。

文件路径: postcss.config.js

1
2
3
4
5

module.exports = {
  plugins: {
    'autoprefixer': {}, // 直接启用 autoprefixer 插件
  },
};

完成了！ 就是这么简单。现在，当 Vite 处理你的 CSS 文件时，会自动通过 PostCSS 和 autoprefixer，为你的样式添加必要的浏览器前缀，确保最佳的兼容性。

9.6. Vite 插件开发与应用

9.6.1. 核心机制：在实战中理解插件如何工作

理论是枯燥的，让我们从一个最简单的“痛点”出发，用实战来开启 Vite 插件的大门。

痛点场景：在开发过程中，我们想知道 Vite 究竟处理了我们项目中的哪些文件，希望能 在每次文件被转换时，在终端打印出它的路径。

这是一个 Vite 自身配置项无法满足的需求，却是插件的完美用武之地。

第一步：创建你的第一个插件

1. 在项目根目录创建一个 plugins 文件夹，用于存放我们自定义的插件。
2. 在 plugins 文件夹中，创建一个 vite-plugin-inspect.ts 文件。

现在，写入我们插件的核心代码：

文件路径: plugins/vite-plugin-inspect.ts

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

import type { Plugin } from 'vite';

export default function inspectPlugin(): Plugin {
  return {
    // 插件名称，用于调试和错误信息输出
    name: 'vite-plugin-inspect',

    // transform 是一个钩子，在每个模块请求被转换时调用
    transform(code, id) {
      // code 是文件源代码，id 是文件的绝对路径
      console.log('Vite 正在处理:', id);
      
      // 我们这里只打印，不修改代码，所以返回 null
      return null;
    }
  };
}

第二步：在 vite.config.ts 中使用它

1
2
3
4
5
6
7
8

import { defineConfig } from 'vite';
import inspectPlugin from './plugins/vite-plugin-inspect'; // 1. 导入我们的插件

export default defineConfig({
  plugins: [
    inspectPlugin(), // 2. 将插件实例放入 plugins 数组
  ],
});

第三步：见证实战效果

现在，启动你的开发服务器：

1

pnpm dev

当你刷新浏览器页面时，观察你的终端，会看到 Vite 打印出了它处理的每一个文件！

1
2
3
4
5

Vite 正在处理: D:/web/vite-magic-show/src/main.ts
Vite 正在处理: D:/web/vite-magic-show/src/style.css
Vite 正在处理: D:/web/vite-magic-show/src/counter.ts
Vite 正在处理: D:/web/vite-magic-show/node_modules/.pnpm/vite@7.1.3/node_modules/vite/dist/client/client.mjs
Vite 正在处理: D:/web/vite-magic-show/node_modules/.pnpm/vite@7.1.3/node_modules/vite/dist/client/env.mjs

通过这个简单的实践，我们已经可以开始剖析插件的核心机制了。

插件的本质

正如你所见，一个 Vite 插件就是一个返回特定对象的 JavaScript 函数。这个对象必须有一个 name 属性用于识别，其核心则是一系列被称为 钩子 (Hooks) 的函数（如我们刚才用的 transform）。Vite 在构建流程的特定阶段会自动调用这些钩子。

API 架构：兼容 Rollup 并扩展

我们刚才使用的 transform 钩子，实际上是继承自 Rollup 的。Vite 的插件 API 是 Rollup 插件接口的一个 超集。这意味着，绝大多数 Rollup 插件都能直接在 Vite 中使用，让 Vite 共享了一个庞大而成熟的生态。

同时，Vite 增加了许多 独有的钩子 来控制开发服务器。让我们来为刚才的插件增加一个 Vite 独有钩子 configureServer，它只在 pnpm dev 启动时运行一次。

文件路径: plugins/vite-plugin-inspect.ts (升级版)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

import type { Plugin, ViteDevServer } from 'vite';

export default function inspectPlugin(): Plugin {
  return {
    name: 'vite-plugin-inspect',

    // configureServer 是 Vite 独有的钩子
    configureServer(server: ViteDevServer) {
      // server 参数是 Vite 开发服务器的实例
      console.log(
        '\n  ✨ 欢迎使用 Prorise 插件，开发服务器已启动！ ✨\n'
      );
    },

    transform(code, id) {
      console.log('Vite 正在处理:', id);
      return null;
    }
  };
}

现在再次运行 pnpm dev，你会在启动信息后看到我们自定义的欢迎语。这个 configureServer 钩子就是 Vite 强大开发体验的扩展点之一。

执行顺序与 enforce 属性

当使用多个插件时，它们的执行顺序由 enforce 属性决定，分为三个阶段：

1. pre: 在 Vite 核心插件 之前 执行。
2. default: 在 Vite 核心插件 之后 执行。（默认值）
3. post: 在 Vite 构建插件 之后 执行。

例如，如果你希望你的日志插件总是在所有其他插件转换代码 之前 运行，你可以这样配置：

1
2
3
4
5
6
7

// vite.config.ts
export default defineConfig({
  plugins: [
    inspectPlugin({ enforce: 'pre' }), // 将插件的执行时机提前
    // ... other plugins
  ],
});

9.6.2. 核心钩子“配方”：深入 Vite 构建的生命周期

在正式开始前，我们先为插件开发 准备好类型环境，这是所有后续实战的基础。

环境准备：安装 Node.js 类型定义

1

pnpm add -D @types/node

安装后，TypeScript 就不会再对 Node.js 的相关 API 报错了。

本节，我们将通过下表中一系列源于真实开发痛点的“插件配方”，来学习最有代表性的钩子函数。

配方一：注入动态构建信息 (config)

Vite 启动时：当 Vite 读取 vite.config.js 文件并初始化配置时，会调用插件的 config 钩子。

痛点: 我们希望在应用中展示版本号、构建时间或最新的 Git 提交信息，以便于测试和追溯问题，但这些信息是动态的，手动维护非常麻烦。

解决方案: 利用 config 钩子，统一收集所有需要的构建时信息，并通过 Vite 的 define 选项，安全、干净地注入到一个全局常量中。

插件实现: plugins/vite-plugin-app-info.ts

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

import type { Plugin } from 'vite';
import { readFileSync } from 'fs';
import { resolve } from 'path';
import { execSync } from 'child_process'; // 用于执行 shell 命令

// 获取 Git 提交的短哈希值
function getGitCommitHash() {
  try {
    return execSync('git rev-parse --short HEAD').toString().trim();
  } catch (e) {
    console.warn('获取 Git Commit 哈希失败:', e);
    return 'N/A';
  }
}

export default function appInfoPlugin(): Plugin {
  return {
    name: 'vite-plugin-app-info',
    config() {
      const CWD = process.cwd();
      // 读取 package.json
      const pkg = JSON.parse(readFileSync(resolve(CWD, 'package.json'), 'utf-8'));
      
      const appInfo = {
        version: pkg.version,
        commitHash: getGitCommitHash(),
        buildTime: new Date().toISOString(),
      };
      
      // 通过 define 选项注入全局变量
      return {
        define: { __APP_INFO__: JSON.stringify(appInfo) },
      };
    },
  };
}

效果验证:

1. 在 src/vite-env.d.ts 中声明全局类型。
2. 在 src/main.ts 中使用 __APP_INFO__ 变量并将其显示在页面上。每次构建，这些信息都会自动更新。

配方二：创建动态 Mock 服务 (configureServer)

Vite 启动开发服务器时（即运行 vite 或 vite dev 命令时）

痛点: 后端接口未就绪或不稳定，导致前端开发被阻塞。

解决方案: 利用 configureServer 钩子向 Vite 开发服务器中注入一个自定义中间件，该中间件 动态加载 mock/ 目录下的所有模块化配置文件，并结合 mockjs 生成动态数据，完美实现 热更新。

插件实现: plugins/vite-plugin-api-mock.ts

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

import type { Plugin } from 'vite';
import { globSync } from 'glob'; // glob 用于查找匹配特定规则的文件路径
import Mock from 'mockjs';

export default function apiMockPlugin(): Plugin {
  return {
    name: 'vite-plugin-api-mock',
    apply: 'serve', // 仅在开发模式下生效
    async configureServer(server) {
      const mockFiles = globSync('mock/**/*.ts', { cwd: process.cwd() });

      // 使用 Vite 的 ssrLoadModule 加载模块，这是实现热更新的关键！
      // 它能加载最新的模块代码（包括 TS），且会自动处理编译。
      for (const file of mockFiles) {
        const mockModule = await server.ssrLoadModule(`/${file}`);
        const mockConfig = mockModule.default;
        
        // 简单演示：在服务器中间件中注册 mock 路由
        server.middlewares.use((req, res, next) => {
          if (req.url === mockConfig.url) {
            const responseData = Mock.mock(mockConfig.response(req));
            res.setHeader('Content-Type', 'application/json');
            res.end(JSON.stringify(responseData));
            return;
          }
          next();
        });
      }
    }
  };
}

效果验证:

1. 安装 mockjs 和 glob。

1

pnpm add -D mockjs glob

2. 创建 mock/user.ts 文件并定义 mock 数据结构。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

// 我们导出一个符合特定结构的对象
export default {
    // 匹配的请求 URL
    url: '/api/user-info',
    // 匹配的请求方法，默认为 'get'
    method: 'get',
    // 模拟接口延迟，单位是毫秒
    delay: 200,
    // 响应函数，返回的数据可以是静态的，也可以使用 mockjs 语法
    response: () => {
      return {
        code: 200,
        message: 'Success',
        data: {
          id: '@id',
          name: '@cname', // 使用 mockjs 的占位符生成中文名
          email: '@email',
          age: '@integer(18, 60)',  
          role: '@pick(["admin", "editor", "guest"])', // 从列表中随机选取一个
        },
      };
    }
  };