Babel 配置实战：大型项目构建提速的 5 个决策点

Babel 配置实战：大型项目构建提速的 5 个决策点

【免费下载链接】babel-handbook:blue_book: A guided handbook on how to use Babel and how to create plugins for Babel.项目地址: https://gitcode.com/gh_mirrors/ba/babel-handbook

当一次 clone 后的冷构建要跑 4 分钟、一次保存要等 20 秒才出结果时，就该认真对待 Babel 配置了：全文共 5 个决策点——按阶段选型、最小配置、速度、包体积、质量与协作，熟悉 npm 但对构建管线没概念的人，可对照仓库里的 Babel Handbook 查细节。

选型速查：按项目阶段对号入座 📋

先对号入座，再往下读：不同阶段的配置重心完全不同，用错阶段配置是返工的最大来源。

项目阶段	推荐配置	不该做的事
个人项目、练手	@babel/preset-env+ 一份最小.babelrc	不装一堆插件凑"专业感"
团队日常开发（10 人以上）	预设 +@babel/plugin-transform-runtime，环境差异走env块	不把环境判断散落在各业务文件里
发布组件库	babel src -d lib整体编译，助手统一交给@babel/runtime	不把 polyfill 打进产物替使用方做决定
打包器已内置 Babel（如 Vite）	直接用构建工具的内置支持	不重复挂一层babel-loader链
多环境部署	targets按环境切换：开发node: current，生产用浏览器列表	不维护三份几乎一样的配置文件

10 分钟跑通最小 Babel 配置

装一次，全部作为开发依赖，装到项目本地而不是全局——不同项目可能锁定不同版本，本地安装避免了对机器环境的隐式依赖：

npm install --save-dev @babel/core @babel/cli @babel/preset-env

根目录放一个文件.babelrc，最小可用形态：

{ "presets": [ ["@babel/preset-env", { "targets": { "node": "current" } }] ] }

注意三点：

• presets是插件的集合，什么都不配时 Babel 默认不做任何转换，所以@babel/preset-env是唯一"必选项"。
• package.json的 scripts 里加"build": "babel src -d lib"，npm run build即可整目录编译。
• 面向浏览器交付时，把targets换成 browserslist 写法，如["last 2 versions", "> 1%", "not dead"]。

先跑通，再优化；需要扩展时从下面列表挑，一次只加一条：

• 写 TypeScript：加@babel/preset-typescript
• 用 class fields 这类提案语法：加@babel/plugin-proposal-class-properties
• 要支持老浏览器：useBuiltIns: "usage"+core-js3，别再整体引入@babel/polyfill
• 开发与生产插件不同：放env块里，由NODE_ENV驱动

四个维度各取一瓢 ⚡

每个维度只给一条动作，外加一句适用条件。

速度——开缓存。Webpack 构建里给babel-loader打开cacheDirectory: true，想让缓存读写更快再设cacheCompression: false。适用条件：构建耗时已经成为团队抱怨点才值得做，小项目开了也感知不到。

包体积——按需注入 polyfill。@babel/preset-env设useBuiltIns: "usage"配corejs: 3，只注入代码里真正用到的 API。适用条件：需要兼容老浏览器、且 core-js 占体积明显；目标是现代浏览器就别动。

质量——让 Linter 认识新语法。ESLint 的 parser 指向babel-eslint，lint 不再对新语法误报。适用条件：linter 一碰到新语法就报错就先换 parser，规则再按eslint:recommended起步，不要一次开满 strict。

协作——把预设收进共享包。把团队共用的 preset 打成内部预设包（如babel-preset-team-config），版本固定在 devDependencies。适用条件：10 人以上、同仓库多个子项目，能省掉"你本机构建为什么和我不一样"的反复沟通；别急着搬进 monorepo，先把单项目的.babelrc跑稳。

3 种高频构建报错的根因 🐛

这三类问题占了日常 Babel 故障的大头：先看症状，再改配置，别盲调参数。

症状	根因	一条命令或配置
冷启动后首次构建慢得离谱，之后增量才正常	Babel 默认不缓存，每次都全量重算	babel-loader规则加cacheDirectory: true
包体积莫名涨了数百 KB	全量 polyfill 被打进来，或开发专用插件混进了生产包	useBuiltIns: "usage"，开发插件挪进env.development
新浏览器正常，老浏览器抛is not a function	转译只翻译语法、不补 API，运行时缺了原生方法	按目标环境精确写 browserslist，缺失的 API 交给 core-js 3

收尾：一条判断标准

开发机复现不了问题、团队也没人抱怨构建时间，就别加配置——每多一个插件就多一分维护成本；同一个坑反复有人踩，才一次加一项，且每轮只改一个变量，好判断到底哪条起了作用。

安装细节、.babelrc完整写法与插件开发，可查仓库内的中文手册：Babel 用户手册。

【免费下载链接】babel-handbook:blue_book: A guided handbook on how to use Babel and how to create plugins for Babel.项目地址: https://gitcode.com/gh_mirrors/ba/babel-handbook