企业官网建设流程全解析

• 开发工具
• 前端构建

本篇技术指南聚焦 Create React App Configuration Override（CRACO）提供的babel配置区块，讲解如何在不弹出（eject）Create React App 的前提下，通过craco.config.js覆写 Babel 的 presets、plugins 与 babel-loader 选项。读者读完将掌握babel.presets、babel.plugins、babel.loaderOptions三种配置形式的写法与函数式覆写模式，并理解 CRACO 底层是如何定位并修改 babel-loader 的。

概览：CRACO 的babel配置区块

CRACO 的配置文件（默认位于项目根目录的craco.config.js，其他可用文件名与查找优先级见 getting-started.md）支持一个顶层babel字段，用于集中定制 Babel 转译行为：

module.exports = { // ... babel: { presets: [ /* ... */ ], plugins: [ /* ... */ ], loaderOptions: { /* ... */ }, loaderOptions: (babelLoaderOptions, { env, paths }) => { /* ... */ return babelLoaderOptions; }, }, };

上方轮廓中出现两次的属性（例如loaderOptions），既可以赋值为对象字面量，也可以赋值为函数，两者的语义差异请参阅 getting-started.md 中的 Object literals and functions 小节。从类型定义上看，babel区块实际支持四个字段，见 config.ts：

export interface CracoBabelConfig { presets?: any[]; plugins?: any[]; assumptions?: { [assumption: string]: boolean }; loaderOptions?: Configure<TransformOptions, BaseContext>; }

其中assumptions字段是源码层面对配置类型的补充（本文后续会讲解它在底层是如何被写入 loader 的），而presets、plugins与loaderOptions即本指南的主角。

babel.presets：追加任意 Babel 预设

babel.presets的类型为[string | [string, object]]，即数组中的每一项可以是预设名字符串（如'@babel/preset-env'），也可以是[预设名, 选项对象]的二元组形式（如['@babel/preset-env', { targets: 'defaults' }]）。此处可传入任何 Babel 官方或第三方预设。

底层行为：追加而非覆盖

CRACO 对 presets 的处理是追加合并，而不是整体替换。核心实现位于 babel.ts：

function addPresets(loader: RuleSetRule, babelPresets: any[]) { if (isArray(babelPresets)) { if (loader.options && !isString(loader.options)) { if (loader.options.presets) { loader.options.presets = loader.options.presets.concat(babelPresets); } else { loader.options.presets = babelPresets; } } else { loader.options = { presets: babelPresets, }; } } log('Added Babel presets.'); }

也就是说：如果 babel-loader 的options里已经有presets（例如 CRA 自带@babel/preset-env、@babel/preset-react），CRACO 会把你在配置中给出的 presets 用concat追加到末尾；如果原先没有 presets，则直接设置为新数组。这一追加策略保证了你不会误删 CRA 的默认预设。

实测验证：presets 追加语义

仓库中的单元测试对“追加而非覆盖”做了直接验证，见 babel.test.js：

expect(babelConfig.presets).toContain('@babel/preset-env'); expect(babelConfig.presets).toContain('@babel/preset-react'); // 自定义预设被追加进来 expect(babelConfig.presets).toContain('@babel/preset-typescript');

对应测试配置 craco.config.js 通过babel.loaderOptions.presets传入三个预设，而模拟的 CRA 原始配置 babel.config.mock.js 只含前两个；测试断言合并后结果同时包含两者且数量不少于原始配置，印证了追加语义。

module.exports = { babel: { presets: ['@babel/preset-typescript'], }, };

babel.plugins：追加任意 Babel 插件

babel.plugins的类型同样是[string | [string, object]]，每一项可以是插件名字符串或[插件名, 选项对象]二元组。常见用法包括启用装饰器语法、按需引入组件库等。

底层行为：与 presets 相同的追加逻辑

插件处理与 presets 完全对称，见 babel.ts：若 loader 的options.plugins已存在则concat追加，否则新建数组。同时注意，presets 与 plugins 的处理互不干扰——CRACO 会先合并 presets，再合并 plugins，各自独立追加。

module.exports = { babel: { plugins: [ ['@babel/plugin-proposal-decorators', { legacy: true }], ['import', { libraryName: 'antd', style: 'css' }], ], }, };

未命中 babel-loader 时的处理

overrideBabel（babel.ts）通过getLoaders(webpackConfig, loaderByName('babel-loader'))在 webpack 的module.rules中递归查找所有 babel-loader（递归逻辑支持use、oneOf、loader 数组等嵌套结构，见 loaders.ts）。如果一个 babel-loader 都找不到，CRACO 会记录错误日志Cannot find any Babel loaders.并直接返回原 webpack 配置，不会静默失败，也不会抛出异常中断构建。这意味着babel区块依赖 CRA 内部存在 babel-loader——只要你的项目仍由 react-scripts 驱动，这一点总是成立的。

babel.loaderOptions：细粒度覆写 babel-loader 选项

babel.loaderOptions是babel区块中最灵活的一项，类型为：

BabelLoaderOptions | (options: BabelLoaderOptions, { env, paths }) => BabelLoaderOptions

它可以接收 babel-loader 支持的任何选项（cacheDirectory、presets、plugins、configFile、babelrc 等），也可以是一个返回新选项对象的函数。与前面两个属性不同，loaderOptions对原配置的处理方式是深度合并或函数全权接管，两者语义差别很大。

形式一：对象字面量（深度合并）

module.exports = { babel: { loaderOptions: { cacheDirectory: true, presets: ['@babel/preset-env', '@babel/preset-react'], }, }, };

当loaderOptions是普通对象时，CRACO 调用deepMergeWithArray将你提供的选项与 loader 现有options深度合并，见 babel.ts：

loader.options = deepMergeWithArray( {}, loader.options || {}, loaderOptions );

深度合并意味着嵌套对象（例如presets数组、env配置）会被逐层合并而非整层覆盖，适合只想局部调整、保留 CRA 其余默认选项的场景。测试配置 craco.config.js 正是通过这种形式追加@babel/preset-typescript并保留了原有预设。

形式二：函数（全权接管）

module.exports = { babel: { loaderOptions: (babelLoaderOptions, { env, paths }) => { if (env === 'production') { babelLoaderOptions.plugins = [ ...(babelLoaderOptions.plugins || []), 'transform-remove-console', ]; } return babelLoaderOptions; }, }, };

函数形式接收两个参数：第一个是当前的 loader options（即 CRA 原始 babel-loader 配置，在调用函数前已被 presets/plugins/assumptions 的追加逻辑处理过）；第二个是上下文对象{ env, paths }，其中env是当前NODE_ENV（development、production、test 等），paths是 CRA 使用的全部路径集合（字段定义见 context.ts）。

底层实现在 babel.ts：函数形式把 loader 的 options整体替换为函数返回值，因此你拥有完全控制权——既可以原地修改并返回原对象，也可以返回一个全新对象。唯一需要警惕的是：

if (!loader.options) { throw new Error( "craco: 'babel.loaderOptions' function didn't return a loader config object." ); }

函数必须返回一个 loader 配置对象，否则 CRACO 会抛出上述错误，构建直接失败。这是函数形式与对象形式在失败模式上的关键差异。

函数与对象的选择建议

• 需要保留 CRA 默认 Babel 配置、只做增量修改时，优先用对象字面量（深度合并），这也是测试中验证过的主路径；
• 需要根据环境变量或路径做条件分支、精确控制最终 options时，用函数形式，但务必保证所有分支都返回对象。

补充：babel.assumptions 的底层支持

虽然官方配置文档未单列小节，但类型定义与源码均支持babel.assumptions字段，用于声明 Babel 对代码的某些假设以换取更小的输出体积。处理逻辑见 babel.ts：它会与 loader 现有assumptions做浅层展开合并，并记录日志Added Babel assumptions.。

module.exports = { babel: { assumptions: { noDocumentAll: true, setPublicClassFields: true, }, }, };

执行时序：babel 覆写在整个配置流程中的位置

babel区块的覆写不是独立运行的，它嵌在 webpack 配置合并流水线中。从 merge-webpack-config.ts 可以看到，mergeWebpackConfig按固定顺序执行：先overrideBabel，再依次处理 ESLint、样式（style）、TypeScript，随后处理webpack.alias/plugins/configure，最后应用自定义 CRACO 插件。而开发与生产构建的 webpack 配置都会走这条流水线（见 override.ts，overrideWebpackDev与overrideWebpackProd均调用mergeWebpackConfig）。

这一顺序带来一个实用推论：webpack.configure（以及自定义插件）中看到的 loader 选项，已经是babel区块覆写后的结果。如果你需要基于最终 Babel 配置做更进一步的 webpack 级修改，应放在webpack.configure而非babel.loaderOptions之前依赖任何中间状态。

常见问题与排查

• Cannot find any Babel loaders.：说明 webpack 配置中定位不到babel-loader。请确认项目确实由 react-scripts / CRA 驱动，且没有被其他插件或webpack.configure提前移除 babel-loader。若使用了自定义 react-scripts 分支，可通过顶层reactScriptsVersion指定包名（见 getting-started.md）。
• 函数形式忘记返回对象：CRACO 会抛出didn't return a loader config object错误，请检查loaderOptions函数的所有分支是否都有返回值。
• presets/plugins 看似未生效：请确认目标代码确实经过 babel-loader 转译（例如被oneOf规则分流），并优先检查日志中是否出现Added Babel presets./Added Babel plugins./Applied Babel loader options.三条日志，它们分别对应三段覆写逻辑的执行成功。
• 与 Jest 的关系：babel区块只影响 webpack 构建链路上的 babel-loader；Jest 的 Babel 转译由jest.babel独立控制（addPresets/addPlugins开关，见 config.ts）。如果测试环境下也要使用同样的自定义预设/插件，需要单独在jest区块配置，或使用babel.config.js这类被 Jest 与 babel-loader 共同读取的全局 Babel 配置文件。

小结

CRACO 的babel区块用三个配置属性覆盖了 Babel 定制的主要场景：presets与plugins采用追加合并语义，安全地扩展现有转译能力；loaderOptions则提供深度合并与函数接管两种粒度，支持按env/paths做环境敏感的动态配置。配合assumptions字段与完整的源码实现（babel.ts）、类型定义（config.ts）和追加语义的单元测试（babel.test.js），你可以在不弹出 CRA 的前提下，安全、可控地完成绝大多数 Babel 定制需求。

• 开发工具
• 前端构建