企业官网建设流程全解析

• 开发工具
• 前端构建

CRACO（Create React App Configuration Override）作为 Create React App 的配置覆盖层，其核心价值不仅在于通过craco start、craco build、craco test等命令直接改造构建流程，还在于对外暴露了一套可编程的Configuration API。本篇文章聚焦于 configuration-api.md 文档所讲解的核心内容：如何在第三方工具（如独立的 Jest 配置文件、自定义 Webpack 配置文件、编辑器插件、CI 脚本等）中，直接获取到 CRACO 处理之后的最终 Jest 与 Webpack 配置。读完本文，你将掌握createJestConfig、createWebpackDevConfig、createWebpackProdConfig三个 API 的完整签名、参数语义、使用前提与实战写法，并理解它们背后的配置加载、上下文构造与合并流程。

一、Configuration API 解决什么问题

在常规用法中，CRACO 通过替换react-scripts的脚本（craco start等）在进程内部完成配置覆盖。但如果你希望把 CRACO 生成的配置导出给其他工具消费——例如：

• 用一份独立的jest.config.js驱动 IDE 的 Jest 集成（VS Code、WebStorm 等）；
• 在 CI 中对生成的 Webpack 配置做二次检查或定制；
• 为可视化构建工具、性能分析工具提供真实的构建配置；
• 编写自己的脚本，复用 CRACO 的合并逻辑而不必重新实现一遍。

此时就需要 Configuration API。该 API 目前支持Jest与Webpack两大构建链路，二者在 packages/craco/src/index.ts 中作为包的公开导出面暴露：

export { createJestConfig, createWebpackDevConfig, createWebpackProdConfig, createDevServerConfigProviderProxy, // ... 其他工具函数 };

二、Jest：createJestConfig

1. 函数签名与参数

createJestConfig(cracoConfig, context = {}, options = { verbose: false, config: null })

该函数接收三个参数，返回一个完整的 Jest 配置对象（类型为JestConfig.InitialOptions）：

options中的两个字段与 packages/craco/src/lib/args.ts 中定义的 CLI 参数解析规则一一对应：

const args: CliArgSpec = { verbose: { arg: '--verbose', value: false }, config: { arg: '--config', value: true }, };

• verbose传入true时开启详细日志，便于排查合并过程；
• config可以传入自定义 CRACO 配置文件的路径（字符串），其优先级与 config.ts 中getConfigPath的解析逻辑一致：显式config优先于package.json中的cracoConfig字段，也优先于根目录自动探测的craco.config.*/.cracorc*文件。

2. 典型用法：导出独立的 jest.config.js

const { createJestConfig } = require('@craco/craco'); const cracoConfig = require('./craco.config.js'); const jestConfig = createJestConfig(cracoConfig); module.exports = jestConfig;

这份文件可以直接替代package.json中的"jest"字段，让 IDE 或 CI 中的 Jest 直接使用 CRACO 合并后的配置，而不必经过craco test命令。

3. 重要前提：不接受函数形式的 cracoConfig

createJestConfig不接受cracoConfig作为函数。如果你的craco.config.js导出的是一个函数（例如为了按env动态生成配置），必须先自己调用它，拿到对象后再传入：

const cracoConfigFactory = require('./craco.config.js'); const cracoConfig = cracoConfigFactory({ env: process.env.NODE_ENV }); const jestConfig = createJestConfig(cracoConfig);

这一限制在源码中有明确体现——packages/craco/src/lib/features/jest/api.ts 的createJestConfig实现开头直接对函数类型抛出错误：

if (isFunction(callerCracoConfig)) { throw new Error("craco: 'cracoConfig' should be an object."); }

（注意：这里的"函数"是指craco.config.js导出的顶层配置函数，与 CRACO 配置内部jest.configure支持函数是两回事。）

4. 底层执行流程

从 packages/craco/src/lib/features/jest/api.ts 的源码可以看到createJestConfig的完整调用链：

1. 校验：cracoConfig必填，且必须是对象；
2. 环境变量兜底：若process.env.NODE_ENV未设置，默认置为'development'；
3. 参数注入：setArgs(options)，让后续getConfigPath等逻辑感知--config与--verbose；
4. 构造 context：以{ env: process.env.NODE_ENV, ...callerContext }合并出JestContext；
5. 处理 CRACO 配置：processCracoConfig(cracoConfig, context)，将用户配置与DEFAULT_CONFIG深合并，并执行 CRACO 插件（见 config.ts）；
6. 解析 CRA 路径：context.paths = getCraPaths(cracoConfig)，从react-scripts的config/paths.js读取全部路径；
7. 加载 CRA 的 Jest 配置提供者：loadJestConfigProvider(cracoConfig)，即react-scripts的scripts/utils/createJestConfig.js；
8. 合并：mergeJestConfig(cracoConfig, craJestConfigProvider, context)，输出最终 Jest 配置。

最终合并阶段（merge-jest-config.ts）还会做两件重要的事：

• 依据cracoConfig.jest.babel.addPresets/addPlugins，用 CRACO 自带的 jest-babel-transform 覆盖 CRA 默认的 Babel transformer，并把cracoConfig挂到jestConfig.globals._cracoConfig上供 transformer 读取；
• 对jest.configure（对象或函数）执行合并，并应用jest相关的 CRACO 插件。

三、Webpack：createWebpackDevConfig与createWebpackProdConfig

1. 函数签名与参数

createWebpackDevConfig(cracoConfig, context = {}, options = { verbose: false, config: null }) createWebpackProdConfig(cracoConfig, context = {}, options = { verbose: false, config: null })

两个函数签名完全一致，差别仅在加载的 CRA 构建配置与环境变量：

• createWebpackDevConfig—— 对应development环境，加载react-scripts/config/webpack.config.js（旧版本则为webpack.config.dev.js）；
• createWebpackProdConfig—— 对应production环境，加载同一份webpack.config.js（旧版本则为webpack.config.prod.js）。

2. 典型用法：导出独立的 webpack.config.js

const { createWebpackDevConfig } = require('@craco/craco'); const cracoConfig = require('./craco.config.js'); const webpackConfig = createWebpackDevConfig(cracoConfig); module.exports = webpackConfig;

同理，生产环境使用createWebpackProdConfig。这类导出常用于需要以"真实构建配置"为输入的工具链，例如自定义打包脚本、构建可视化分析，或把配置交给不经过craco build的独立执行器。

3. 同样不接受函数形式的 cracoConfig

文档明确强调，createWebpackDevConfig与createWebpackProdConfig不接受cracoConfig作为函数；若配置文件导出的是函数，需先手动调用。这一校验同样体现在 packages/craco/src/lib/features/webpack/api.ts 的公共实现createWebpackConfig中：

if (!callerCracoConfig) { throw new Error("craco: 'cracoConfig' is required."); } if (isFunction(callerCracoConfig)) { throw new Error("craco: 'cracoConfig' should be an object."); }

4. 底层执行流程

两个 Webpack API 内部共用同一个createWebpackConfig实现（api.ts），流程与 Jest 版本高度对称：

1. 校验配置必填且为对象；
2. 若NODE_ENV未设置，按目标环境兜底（dev 为'development'，prod 为'production'）；
3. setArgs(options)注入 CLI 参数；
4. 构造WebpackContext：{ env: process.env.NODE_ENV, ...callerContext }；
5. processCracoConfig处理用户配置（含插件）；
6. context.paths = getCraPaths(cracoConfig)；
7. 通过loadWebpackDevConfig/loadWebpackProdConfig（见 cra.ts）加载 CRA 原始 Webpack 配置；
8. 调用mergeWebpackConfig完成全部覆盖合并并返回。

5. Webpack 合并阶段做了什么

mergeWebpackConfig（merge-webpack-config.ts）是 Webpack 链路的枢纽，依次执行：

• 内置特性覆盖：overrideBabel、overrideEsLint、overrideStyle、overrideTypeScript，对应 babel.ts、eslint.ts、style/style.ts、typescript.ts；
• alias 合并：webpack.alias追加到resolve.alias；
• 插件增删：兼容旧式plugins: [...]数组直接追加，也支持plugins: { add: [...], remove: [...] }；按"先 remove 后 add"的顺序处理（removePluginsFromWebpackConfig / addPlugins）；
• configure 总控：webpack.configure若为对象则用webpack-merge合并，若为函数则把(webpackConfig, context)交给你完全掌控；
• 应用 Webpack 相关 CRACO 插件。

也就是说，通过createWebpackDevConfig/createWebpackProdConfig拿到的，与craco start/craco build内部实际使用的配置是同一条合并流水线的产物。

四、context 与 options 的深层语义

1. context 对象的结构

三个 API 的第二个参数context都以BaseContext为基座（见 packages/craco-types/src/context.ts）：

export interface BaseContext { env?: string; // 当前 NODE_ENV paths?: CraPaths; // CRA 使用的全部路径 }

其中paths由 CRACO 在内部自动填充（来自react-scripts的config/paths.js），包含appPath、appSrc、appBuild、appHtml、appIndexJs等字段，这与 configuration/getting-started.md 中"上下文对象{ env, paths }"的描述一致。

对于 Jest 场景，createJestConfig传入的 context 会被扩展为JestContext，额外拥有两个 CRA 提供的属性：

• resolve—— 解析react-scripts内部模块路径的函数；
• rootDir—— 项目根目录。

（见 jest.md 与JestContext类型定义。）

2. options 与 CLI 的对应关系

options对象不是花架子——它会被setArgs写入 CRACO 的全局参数区（args.ts），从而影响后续的配置加载：

• config：指定自定义 CRACO 配置文件的路径，等价于 CLI 的--config；
• verbose：开启日志输出，等价于--verbose。

如果你在脚本中直接调用这些 API，同时又希望它们读取--config指定的配置文件，可以像这样显式传入：

const webpackConfig = createWebpackDevConfig(cracoConfig, {}, { config: './config/my-craco-config.js', verbose: true, });

五、实战组合：在第三方工具中完整复用 CRACO

1. 与 IDE Jest 集成

多数 IDE 会优先读取根目录的jest.config.js。将createJestConfig的产物作为默认导出，即可让 IDE 的测试运行器与craco test使用完全一致的 Jest 配置：

const { createJestConfig } = require('@craco/craco'); const cracoConfig = require('./craco.config.js'); // 按需传入环境，例如 CI 中为 'test' const jestConfig = createJestConfig(cracoConfig, { env: 'test' }); module.exports = jestConfig;

2. 生成 Webpack 配置供分析脚本使用

const { createWebpackProdConfig } = require('@craco/craco'); const cracoConfig = require('./craco.config.js'); const webpackConfig = createWebpackProdConfig(cracoConfig); // 检查最终产物中是否包含预期的插件 const hasHtmlPlugin = webpackConfig.plugins.some( (p) => p.constructor && p.constructor.name === 'HtmlWebpackPlugin' ); console.log('HtmlWebpackPlugin present:', hasHtmlPlugin);

3. 函数式 craco.config.js 的适配

如果项目配置是函数形式（getting-started.md 的导出方式），务必先调用再传入：

const cracoConfigFactory = require('./craco.config.js'); const cracoConfig = cracoConfigFactory({ env: process.env.NODE_ENV || 'development' }); const jestConfig = createJestConfig(cracoConfig);

六、常见问题与注意事项

1. 顶层配置函数必须手动调用：三个 API 均不接受函数形式的cracoConfig，这是文档与源码双重确认的硬性约束。
2. NODE_ENV的兜底行为：调用时若环境变量未设置，Jest API 默认补为development，Webpack 则按 dev/prod 对应补值。若你的配置逻辑依赖特定环境，建议在调用前自行设置NODE_ENV。
3. config选项的优先级：options.config指定的路径 >package.json的cracoConfig字段 > 根目录自动探测（craco.config.ts/js/cjs、.cracorc.ts/js、.cracorc等），探测顺序与优先级由 config.ts 中的searchPlaces定义。
4. context.paths 会被自动覆盖：即使你手动传入了paths，getCraPaths的结果也会在processCracoConfig之后覆写context.paths，因此无需（也不建议）手动构造路径。
5. 版本前提：当前仓库中@craco/craco的 peerDependency 为react-scripts: ^5.0.0（见 packages/craco/package.json），上述 API 面向 react-scripts 5.x 设计；旧版 react-scripts 的 legacy 配置文件（webpack.config.dev.js/webpack.config.prod.js）仍由 cra.ts 兼容处理。

结语

CRACO Configuration API 的价值在于把"配置计算"与"构建执行"解耦：createJestConfig、createWebpackDevConfig、createWebpackProdConfig三个函数暴露出与 CLI 完全同源的配置流水线，让任何第三方工具都能拿到真实、完整的最终配置。结合 index.ts 的导出面、api.ts 与 api.ts 的实现，以及 merge-jest-config.ts、merge-webpack-config.ts 的合并细节，你可以在自己的工具链中放心复用这套成熟的配置生成能力。

• 开发工具
• 前端构建