1 / 4概念
Toolchain
工具链把源码变成可运行产物,并把依赖、测试和检查串成可重复的流水线。判断标准不是“工具新不新”,而是冷启动、产物、可复现性和排错成本。
1 概念
1.1 一句话定义
JavaScript/TypeScript 工具链是四类程序的组合:包管理器维护依赖图,打包器把模块图变成产物,测试运行器执行断言,静态检查器在运行前发现问题。类型检查是独立的一步,不包含在打包器里。
1.2 它解决什么问题
- 源码不能直接在浏览器或 Node 里按模块图运行,需要解析、转换和打包。
- 依赖版本、peer 约束和 lockfile 决定构建是否可复现。
- 多人多机环境下,Node/pnpm/包管理器版本不一致会让结果漂移。
- 没有缓存和增量,冷启动与反馈时间会随项目规模线性变差。
1.3 不属于本页的内容
| 主题 | 去哪 |
|---|---|
| 语言语义、类型体操、装饰器 | Values and Syntax |
| React/Vue/Svelte 的运行时模型 | Rendering and Reconciliation |
| Node.js/V8/libuv 的运行时机制 | Runtime Environment |
| CI 平台与流水线编排 | CI/CD |
| ESLint/Prettier 的规则取舍 | Code Quality |
1.4 关键术语
| 术语 | 含义 | 容易混淆的点 |
|---|---|---|
| 依赖图 | 包与包之间的版本约束关系 | 不是模块 import 图 |
| lockfile | 锁定每个包的实际版本与完整性哈希 | 不是 package.json 的替代品 |
| peer dependency | 由使用方提供的依赖,插件常用 | 不是普通 dependency |
| hoisting | 把依赖提升到上层 node_modules | pnpm 默认不扁平提升 |
| phantom dependency | 未声明却能解析到的依赖 | 换包管理器就崩 |
| tree-shaking | 删除未被引用的导出 | 依赖 ESM 静态结构 |
| HMR | 热更新,只替换变化的模块 | 不等于页面刷新 |
| catalog | 工作区内共享的版本来源 | 不是 lockfile |
2 机制
2.1 心智模型
工具链是一条从入口出发的图:resolve → transform → chunk → emit。包管理器维护依赖图,打包器维护模块图,测试运行器复用同一条 transform 管线。四类工具共享“图”这个心智模型,只是节点和边的含义不同。
2.2 机制拆解
- pnpm:内容寻址存储让同一版本只存一份,靠硬链接进入各自
node_modules;非扁平布局让未声明依赖直接解析失败;严格 peer 处理把冲突提前到安装阶段。 - Vite:开发态用浏览器原生 ESM + esbuild 预打包依赖,启动快;生产态用 Rollup 做 tree-shaking 和代码分割。
- Webpack:loader 负责单文件转换,plugin 介入构建生命周期;能力最全,配置也最重。
- Vitest:复用 Vite 的 transform 管线,测试环境与源码转换保持一致;Jest 生态更老,配置独立。
- TypeScript:
tsc --noEmit只做类型检查,不产出 JS;打包器的类型擦除不替代类型检查。
2.3 完整枚举
| 类别 | 代表 | 职责 | 关键配置 |
|---|---|---|---|
| 包管理器 | pnpm、npm、yarn、bun | 依赖解析、安装、lockfile、workspace | packageManager、catalog、.npmrc |
| 打包器 | Vite、Webpack、Rspack、Turbopack、esbuild、Rollup | 模块图、转换、代码分割、压缩 | 入口、alias、define、split chunks |
| 测试运行器 | Vitest、Jest、node:test | 发现测试、隔离环境、断言、覆盖率 | environment、setupFiles、coverage |
| 静态检查器 | ESLint、Biome、oxlint | AST 规则、可自动修复的问题 | rules、plugins、ignore |
| 格式化器 | Prettier、Biome | 统一空白、引号、换行 | printWidth、singleQuote |
| 类型检查器 | tsc | 类型错误、声明文件生成 | strict、paths、noEmit |
2.4 关键数字与量级
| 指标 | 量级 | 说明 |
|---|---|---|
| 冷启动 | 百毫秒到数秒 | Vite 开发态通常明显快于全量打包 |
| HMR 反馈 | 十毫秒到数百毫秒 | 取决于模块边界和状态保留 |
| 依赖安装 | 秒到分钟 | 受网络、store 命中率和 lockfile 影响 |
| 产物体积 | KB 到 MB | 受依赖、sourcemap、polyfill 影响 |
| 类型检查 | 秒到分钟 | 随项目规模和泛型复杂度增长 |
3 实践
3.1 最小示例
{
"packageManager": "pnpm@9.15.9",
"scripts": {
"dev": "vite",
"build": "tsc --noEmit && vite build",
"test": "vitest run",
"lint": "eslint .",
"format:check": "prettier --check ."
}
}
// vite.config.ts:最小可用配置,生产构建保留 sourcemap。
import {defineConfig} from 'vite';
export default defineConfig({
build: {sourcemap: true},
});
3.2 常用操作与参数
| 操作 | 命令 / API | 说明 |
|---|---|---|
| 全仓安装 | pnpm install | 读取 workspace 与 lockfile |
| 可复现安装 | pnpm install --frozen-lockfile | CI 必须使用;lockfile 变更即失败 |
| 只跑某包 | pnpm --filter @moqi/docs dev | 不进入无关包 |
| 查依赖来源 | pnpm why react | 解释版本从哪来 |
| 开发服务器 | vite | 原生 ESM + 预打包依赖 |
| 生产构建 | vite build | Rollup 产物 |
| 单次测试 | vitest run | 不进入 watch 模式 |
| 类型检查 | tsc --noEmit | 与打包分离 |
| 增量诊断 | vite --debug | 查看插件与解析耗时 |
3.3 标准流程
- 用
packageManager锁定包管理器版本;CI 与本地一致。 - 用
pnpm-workspace.yaml的catalog收拢跨包共享版本。 - 安装后先跑
pnpm install --frozen-lockfile,确认 lockfile 没有漂移。 - 开发态跑
vite,生产态跑tsc --noEmit && vite build。 - 测试跑
vitest run,静态检查跑eslint .和prettier --check .。 - 把上述命令固化到 CI,不要依赖本地全局安装。
3.4 与相邻技术的组合
- TypeScript:打包器负责转换,
tsc负责类型;两者都跑才算完整。 - ESLint/Prettier:ESLint 管规则与缺陷,Prettier 管格式;不要让两者互相覆盖。
- CI:
--frozen-lockfile+ 缓存 store + 并行 lint/test/build。 - Monorepo:
workspace:*表达内部依赖,catalog:统一外部版本。
3.5 选型维度
| 维度 | 取值 | 影响 |
|---|---|---|
| 项目类型 | 库 / 应用 / Node 脚本 | 库更看重产物格式,应用更看重开发体验 |
| 冷启动 | 敏感 / 不敏感 | Vite/Turbopack 优先 |
| 产物目标 | 浏览器 / Node / 库 | 决定 format、external、polyfill |
| 生态兼容 | 老项目 / 新项目 | Webpack 插件多,Vite 生态较新 |
| 团队熟悉度 | 高 / 低 | 配置复杂度直接影响排错成本 |
| 可复现性 | 强 / 弱 | 锁版本、锁 lockfile、锁 CI 环境 |
3.6 决策规则
- 新建浏览器应用:Vite;需要极致增量再评估 Turbopack/Rspack。
- 老项目依赖 Webpack loader/plugin:保留 Webpack,逐步替换高成本插件。
- 发布库:Rollup/Vite library mode,明确
exports与peerDependencies。 - Monorepo:pnpm workspaces + catalog;不要混用 npm/yarn。
- 测试:已有 Vite 就用 Vitest;已有 Jest 生态且迁移成本高就保留 Jest。
- 静态检查:ESLint + Prettier 各司其职;新项目可评估 Biome 统一两者。
3.7 替代方案对比
| 方案 | 优势 | 代价 | 适用 |
|---|---|---|---|
| Vite | 冷启动快、配置少 | 老生态插件少 | 新应用、库 |
| Webpack | 生态最全、可控性强 | 配置重、冷启动慢 | 大型老项目 |
| Turbopack | 增量快 | 生态与稳定性仍在演进 | Next.js 新项目 |
| pnpm | 严格、省磁盘、workspace 强 | 幽灵依赖会直接报错 | Monorepo |
| npm | 内置、零学习成本 | 扁平布局、严格性弱 | 单包小项目 |
| Vitest | 复用 Vite 管线、快 | 生态较 Jest 新 | Vite 项目 |
| Jest | 生态成熟、资料多 | 独立配置、转换链路重复 | 老项目 |
3.8 何时不该用
- 单个 Node 脚本:不需要打包器,
node直接跑。 - 只做类型检查:不要为了
tsc引入打包器。 - 团队没有维护能力:不要同时上两套打包器/包管理器。
- 依赖大量非 ESM 老包:Vite 的预打包会踩坑,评估 Webpack 更稳。
4 边界
4.1 典型故障
| 症状 | 根因 | 处理 |
|---|---|---|
| 解析时报模块缺失,但包确实装了 | 未声明依赖,幽灵引用 | 补进 dependencies,不要加 hoist |
| 安装时报 peer 冲突 | 两个包要求不同 major | 升级或显式对齐,不要 --force |
| 改了别的包不生效 | 解析到 lockfile 里的旧版本 | 检查是否用了 workspace:* |
| 开发正常、构建失败 | 开发/生产解析条件不同 | 检查 exports、conditions、define |
| HMR 后状态错乱 | 模块边界或状态保留策略有问题 | 缩小 HMR 边界,必要时整页刷新 |
| 产物重复打包 | 依赖被多次解析或未 external | 检查 dedupe、peer、resolve.dedupe |
| ESM/CJS 互操作报错 | 包同时提供两种格式,导入方式不匹配 | 明确 type、exports 和导入语法 |
| 测试环境与浏览器不一致 | environment 配置错误 | 用 jsdom/happy-dom 或真实浏览器 |
| CI 构建 OOM | 并行度过高或 sourcemap 过大 | 降并发、拆包、关闭不必要的 sourcemap |
4.2 反模式
| 做法 | 后果 | 替代 |
|---|---|---|
用 shamefully-hoist 修解析错误 | 幽灵依赖重新长回来 | 补齐声明 |
| 手改 lockfile | 哈希与依赖树不一致 | 重新安装生成 |
| 仓库里出现第二个 lockfile | 两套解析结果 | 只保留 pnpm-lock.yaml |
在 pnpm 仓库里跑 npm install | 生成第二份依赖树 | 统一用 pnpm |
| 关闭严格 peer 检查 | 冲突推迟到运行时 | 显式对齐版本 |
4.3 可观测信号
pnpm why 查依赖来源,vite --debug 查插件与解析耗时,bundle analyzer 查体积,vitest --coverage 查覆盖,CI 日志查缓存命中与安装时长。
4.4 安全 / 性能 / 一致性边界
- 可复现性:CI 必须
--frozen-lockfile;lockfile 变更要审查。 - 供应链:私有 registry、依赖扫描和 lockfile 完整性哈希是同一道防线。
- 构建确定性:同一 commit、同一包管理器版本、同一 Node 版本应产出相同结果。
- 性能:冷启动和 HMR 是开发体验指标,产物体积和首屏是用户指标,不要混为一谈。