CRACO 使用指南：为 Create React App 添加配置覆盖层，免 eject 自定义 ESLint、Babel 与 PostCSS

开发工具前端构建【免费下载链接】cracoCreate React App Configuration Override, an easy and comprehensible configuration layer for Create React App.项目地址https://gitcode.com/gh_mirrors/cr/craco点击查看免费下载CRACOCreateReactAppConfigurationOverride是面向 create-react-appCRA的配置层它让你在不执行eject的前提下通过项目根目录下单一配置文件如craco.config.js自由定制 Webpack、ESLint、Babel、PostCSS、Jest、DevServer 与 TypeScript 等配置。读完本文你将掌握 CRACO 的安装接入、配置文件的命名与解析规则、CLI 替换步骤以及各配置模块的写法与底层合并原理可直接应用于真实 CRA 项目。CRACO 解决什么问题create-react-app 为 React 工程提供了开箱即用的脚手架但它的内部配置Webpack、Babel、ESLint 等默认不可见、不可改。传统方案是运行npm run eject把全部配置弹出到项目中——代价是丧失官方更新、引入大量模板代码且不可逆。CRACO 在 CRA 之上增加了一层配置覆盖层你只需要在应用根目录添加一个配置文件CRACO 会在运行时读取它、深合并进 CRA 的原始配置再通过改写require.cache的方式把结果还给 react-scripts 的各个脚本。正如项目根 README.md 所述Get all the benefits of Create React Appandcustomization without using eject——既保留 CRA 的全部能力又获得完全的自定义能力。在 npm 上该包名为craco/craco当前仓库中 packages/craco/package.json 标注版本为 7.1.0其peerDependencies声明支持react-scripts^5.0.0CLI 入口为craco对应dist/bin/craco.js。仓库采用 npm workspace 结构核心实现位于 packages/craco/src类型定义位于 packages/craco-types/src配套文档与配方存放在 website 目录。三步快速接入README 给出了非常清晰的接入流程共三步第一步安装依赖将craco/craco安装为项目的开发依赖npm i -D craco/craco第二步创建配置文件在项目根目录与package.json同级创建craco.config.jsmy-app ├── node_modules ├── craco.config.js └── package.json第三步替换 npm scripts把package.json的scripts中所有react-scripts调用替换为craco命令scripts: { - start: react-scripts start start: craco start - build: react-scripts build build: craco build - test: react-scripts test test: craco test }完成以上三步后npm start/npm run build/npm test就都会先经过 CRACO 的配置处理再交给 react-scripts 执行。这也是 integration 测试 验证的核心链路测试项目通过webpack.configure注入DefinePlugin定义全局常量构建后页面中能读到CRACO is working!文本证明自定义配置确实生效。CLI 背后的执行流程替换脚本之后发生了什么从源码看craco start与craco test各有一个专用入口start.ts先将NODE_ENV默认设为development解析 CLI 参数然后loadCracoConfigAsync加载并处理配置依次执行overridePaths、overrideWebpackDev、overrideDevServer最后调用 CRA 原始的start.js。test.ts将NODE_ENV默认设为test加载配置后执行overridePaths与overrideJest再调用 CRA 的test.js。两个入口都在注释中强调findArgsFromCli必须在paths被导入之前调用见 args.ts其解析--verbose与--config两个参数因为 CRA 的路径模块依赖环境变量。核心的偷梁换柱机制在 cra.tsCRACO 通过require.resolve定位 react-scripts 内部的config/webpack.config.js、config/webpackDevServer.config.js、scripts/utils/createJestConfig.js等文件加载出原始配置后合并再通过overrideModule改写require.cache中对应模块的导出。这样当 CRA 脚本真正require这些模块时拿到的已经是 CRACO 处理后的配置。同时在 validate-cra-version.ts 中会校验react-scripts版本semver.gte(version, 5.0.0)不满足时抛出错误提示升级。配置文件的发现与解析支持的配置文件名CRACO 使用cosmiconfig查找配置文件config.ts 中定义了如下搜索顺序从上到下优先级递减package.json中的cracoConfig字段若配置的是路径字符串则作为配置文件路径craco.config.tscraco.config.jscraco.config.cjs.cracorc.ts.cracorc.js.cracorc如果同时存在多个配置文件CRACO 会采用上述列表中排在前面的那一个若都未找到会抛出 Config file not found 错误。craco.config.ts之所以可用是因为 cosmiconfig 注册了 TypeScript loader见 config.ts。自定义配置文件位置除默认文件名外还有两种方式指定自定义位置方式一package.json的cracoConfig字段推荐{ cracoConfig: config/craco-config-with-custom-name.js }方式二CLI 的--config参数向后兼容{ scripts: { start: craco start --config config/craco-config-with-custom-name.js } }需要注意--configCLI 选项不支持 Babel with Jest的组合场景CLI 解析发生在 Jest Babel transform 加载之前见 jest-babel-transform.ts 中首次运行时的异步配置加载逻辑因此官方推荐优先使用package.json字段方式。配置导出方式配置文件支持三种导出形式函数形式会收到包含当前环境变量的对象如NODE_ENV// 1. 对象字面量 module.exports { ... }; // 2. 函数 module.exports function ({ env }) { return { ... }; }; // 3. Promise / Async 函数 module.exports async function ({ env }) { await ...; return { ... }; };源码中 config.ts 的loadCracoConfigAsync专门用于等待 Promise 解析完成start、build、test脚本都走这条异步路径。核心配置概念对象、函数与 context对象字面量 vs 函数CRACO 的多数配置项可以赋两种值对象字面量与 CRA 原始配置做深合并函数接收原始配置作为第一个参数、可选的 context 对象作为第二个参数返回新配置获得完全控制权。module.exports { webpack: { configure: { entry: ./path/to/my/entry/file.js, }, }, };module.exports { webpack: { configure: (webpackConfig, { env, paths }) { webpackConfig.entry ./path/to/my/entry/file.js; return webpackConfig; }, }, };Context 对象{ env, paths }函数形式可选的第二个参数是 context 对象context.ts 中BaseContext定义了两个属性env—— 当前的NODE_ENVdevelopment、production、test 等paths—— CRA 使用的所有路径对象如appSrc、appBuild、appHtml等 20 余个字段。部分配置节会扩展 contextjest.configure额外提供resolve与rootDirdevServer额外提供proxy与allowedHost见 context.ts。覆盖模式Override modes部分配置节eslint、style.postcss提供mode属性extends—— 提供的配置扩展CRA 原始设置默认file—— 重置 CRA 的设置改用你提供的官方配置文件如.eslintrc、postcss.config.js它将完全取代原有设置。默认配置定义在 config.tsstyle.postcss.mode与eslint.mode默认为extendsjest.babel.addPresets与addPlugins默认为true。合并算法数组拼接式深合并CRACO 的合并不是简单浅拷贝。utils.ts 中deepMergeWithArray基于 lodash 的mergeWith实现普通对象递归深合并数组则直接拼接concat。这一策略意味着你在配置中添加的 Babel 插件、PostCSS 插件会追加到 CRA 原有列表之后而不会被覆盖。各配置模块速览CRACO 可配置的顶层键由 packages/craco-types/src/config.ts 定义reactScriptsVersion、style、eslint、babel、jest、typescript、webpack、devServer、plugins、paths。webpack别名、插件增删与完全控制module.exports { webpack: { alias: { components: ./src/components }, plugins: { add: [ /* 要添加的插件 */ ], remove: [ /* 要移除的插件构造器名 */ ], }, configure: { /* ... */ }, // 或 configure: (webpackConfig, { env, paths }) { ...; return webpackConfig; } }, };webpack.alias对象形式Object.assign合并进resolve.aliaswebpack.plugins.add插件数组每个元素可以是插件实例或[plugin, append | prepend]元组。默认是 prepend插入到最前元组形式可显式控制顺序——实现见 webpack-plugins.tswebpack.plugins.remove按插件构造器名称constructor.name过滤移除webpack.configure函数形式拥有最终决定权。Webpack 合并的完整流水线在 merge-webpack-config.ts顺序为overrideBabel→overrideEsLint→overrideStyle→overrideTypeScript→ 处理alias/plugins/configure→ 最后应用第三方插件钩子。仓库中的单元测试 merging.test.js 正是对这一链路的行为验证它会确认 CRA 原有的 JS rule 仍存在、自定义的 SVG loader 与 alias 已加入、输出目录被改写。babelpresets、plugins、assumptions 与 loaderOptionsmodule.exports { babel: { presets: [ /* Babel presets形如 [string | [string, object]] */ ], plugins: [ /* Babel plugins */ ], assumptions: { /* Babel assumptions */ }, loaderOptions: { /* babel-loader 选项 */ }, // 或 loaderOptions: (babelLoaderOptions, { env, paths }) { ...; return babelLoaderOptions; } }, };babel.ts 按名字匹配babel-loader将presets/plugins追加到 loader 选项的对应数组若已存在则concat否则直接赋值assumptions按键合并loaderOptions支持对象深合并或函数完全控制。eslint开关、模式、配置与插件选项module.exports { eslint: { enable: true /* 默认值 */, mode: extends /* 默认值 */ || file, configure: { /* ESLint 配置选项 */ }, // 或 configure: (eslintConfig, { env, paths }) { ...; return eslintConfig; } pluginOptions: { /* eslint-webpack-plugin 选项 */ }, }, };enable: false时直接移除ESLintWebpackPluginmode: file时设置useEslintrc: true并删除baseConfig改用项目的 ESLint 配置文件mode: extends默认时configure会作为baseConfig与 CRA 原有baseConfig深合并。实现细节见 eslint.ts。配方便捷写法见 use-an-eslint-config-file.mdmode: file配合一个extends: [eslint-config-react-app]的.eslintrc.js。styleCSS Modules、Sass 与 PostCSSmodule.exports { style: { modules: { localIdentName: }, css: { loaderOptions: { /* css-loader 选项 */ } }, sass: { loaderOptions: { /* sass-loader 选项 */ } }, postcss: { mode: extends /* 默认值 */ || file, plugins: [require(plugin-to-append)], plugins: (plugins) [require(plugin-to-prepend)].concat(plugins), env: { autoprefixer: { /* autoprefixer 选项 */ }, stage: 3, features: { /* preset-env features */ }, }, loaderOptions: { /* postcss-loader 选项 */ }, }, }, };style.modules.localIdentName覆盖 CSS Modules 的类名生成规则针对 css-loader 2.x/3.x 的不同options.modules结构分别处理见 css.tsstyle.postcss.plugins函数形式接收 CRA 现有插件列表并可决定顺序数组形式追加到末尾style.postcss.env与 CRA 内置的 preset-env 默认配置stage: 3、autoprefixer: { flexbox: no-2009 }深合并后重建 PostCSS 插件链见 postcss.ts 中的CRA_PRESET_ENV与CRA_PLUGINSstyle.postcss.mode: file清空postcssOptions中的插件列表改用项目根目录的postcss.config.js示例见 use-a-postcss-config-file.md其中也展示了POSTCSS_MODES.file常量写法。jestBabel 联动与 configuremodule.exports { jest: { babel: { addPresets: true /* 默认值 */, addPlugins: true /* 默认值 */, }, configure: { /* Jest 配置选项 */ }, // 或 configure: (jestConfig, { env, paths, resolve, rootDir }) { ...; return jestConfig; } }, };jest.babel.addPresets/addPlugins决定是否把babel.presets/babel.plugins同步到 Jest 的 Babel 转换中。当你在babel节配置了 presets/plugins 且这两个开关开启时merge-jest-config.ts 会把 Jest 的 Babel transform 替换为 CRACO 自带的 jest-babel-transform.ts使测试环境的转译与构建环境保持一致jest.configure函数形式额外收到resolveCRA 提供的模块解析函数与rootDir项目根目录两个 context 属性。devServer开发服务器配置module.exports { devServer: { /* webpack-dev-server 选项 */ }, // 或 devServer: (devServerConfig, { env, paths, proxy, allowedHost }) { ...; return devServerConfig; } };override.ts 与 create-config-provider-proxy.ts 的实现显示CRACO 包装 CRA 的webpackDevServer.config.js提供者对象形式用webpack-merge合并函数形式则先拿到 CRA 生成的配置再交给你的函数改写函数 context 额外包含proxyDevServer 代理配置数组与allowedHost。若devServer为对象字面量还会先通过 set-environment-variables.ts 设置相关环境变量。typescript关闭类型检查module.exports { typescript: { enableTypeChecking: true /* 默认值 */, }, };设置为false时生产构建中过滤掉ForkTsCheckerWebpackPlugin见 typescript.ts开发服务器中则改写WebpackDevServerUtils.createCompiler传入useTypeScript: false见 override-utils.ts。plugins接入第三方 CRACO 插件module.exports { plugins: [ { plugin: require(some-craco-plugin), options: { /* 传给插件的选项 */ }, }, ], };插件通过四个可选钩子介入详见 hooks.mdoverrideCracoConfig在 CRACO 处理配置之前、overrideWebpackConfig、overrideDevServerConfig、overrideJestConfig均在 CRACO 处理对应配置之后。每个钩子都只接收一个对象参数cracoConfig/webpackConfig/devServerConfig/jestConfig、pluginOptions、context并且必须返回更新后的配置对象——若返回 undefinedplugins.ts 会直接抛错。完整插件骨架示例见 getting-started.md。实用辅助环境判断与配置导出 APIwhen 系列辅助函数从 index.ts 导出的when、whenDev、whenProd、whenTest可用于按环境条件化配置实现见 user-config-utils.tsmodule.exports { eslint: { mode: file, configure: { formatter: when( process.env.NODE_ENV CI, require(eslint-formatter-vso) ), }, }, webpack: { plugins: [ new ConfigWebpackPlugin(), ...whenDev(() [new CircularDependencyPlugin()], []), ], }, };四个函数签名分别为whenT(condition, fn, [unmetValue])条件为真时调用fn并返回其结果否则返回unmetValue缺省为undefinedwhenDev(fn, [unmetValue])等价于when(process.env.NODE_ENV development, fn, unmetValue)whenProd(fn, [unmetValue])等价于when(process.env.NODE_ENV production, fn, unmetValue)whenTest(fn, [unmetValue])等价于when(process.env.NODE_ENV test, fn, unmetValue)。Configuration API在外部工具中复用 CRACO 配置CRACO 的 Configuration API 支持 Jest 与 Webpack便于把生成的配置交给其他工具const { createJestConfig } require(craco/craco); const cracoConfig require(./craco.config.js); const jestConfig createJestConfig(cracoConfig); module.exports jestConfig;const { createWebpackDevConfig } require(craco/craco); const cracoConfig require(./craco.config.js); const webpackConfig createWebpackDevConfig(cracoConfig); module.exports webpackConfig;对应导出项见 index.tscreateJestConfig、createWebpackDevConfig、createWebpackProdConfig、createDevServerConfigProviderProxy签名均为(cracoConfig, context {}, options { verbose: false, config: null })。需要注意这些 API不接受函数形式的cracoConfig若你的配置文件导出的是函数需先自行调用拿到对象。使用createJestConfig在独立jest.config.js中承载配置的完整示例见 use-a-jest-config-file.md。自定义 react-scripts 包如果你使用的是 create-react-app 官方react-scripts的 fork 分支可以在配置中显式指定包名CRACO 会从该包解析 Webpack/Jest/DevServer 配置与脚本cra.ts 中所有require.resolve都基于该字段module.exports { // ... reactScriptsVersion: custom-react-scripts-package, };省略时默认值为react-scripts这也是 config.ts 中DEFAULT_CONFIG的设定。同时注意版本约束本仓库版本要求react-scripts^5.0.0且启动时会校验主版本号不低于 5因此请确保项目中的 react-scripts 满足该前提。小结CRACO 以单一配置文件 CLI 命令替换的极简方式为 CRA 项目提供了完整的配置自定义能力覆盖 Webpack、Babel、ESLint、StyleCSS/Sass/PostCSS、Jest、DevServer、TypeScript 与插件体系。其底层通过 cosmiconfig 发现配置、lodash 数组拼接式深合并、require.cache改写实现零侵入覆盖。仓库的单元测试merging.test.js与集成测试basic-integration-test为上述行为提供了可复现的验证样例更多实战配方Ant Design、less-loader、HTTPS dev server、PostCSS 扩展等可参考 recipes 目录 与 configuration 文档。赞分享开发工具前端构建【免费下载链接】cracoCreate React App Configuration Override, an easy and comprehensible configuration layer for Create React App.项目地址https://gitcode.com/gh_mirrors/cr/craco点击查看免费下载相关推荐CRACO 完全指南不 eject 也能定制 Create React App 的配置层CRACO 完全指南不 eject 也能定制 Create React App 的配置层 导读 CRACO C reate R eact A pp C on开发工具前端构建CRACOCreate React App Configuration Override完全指南不 eject 定制 CRA 的配置层CRACOCreate React App Configuration Override完全指南不 eject 定制 CRA 的配置层 导读 CRACO开发工具前端构建使用 CRACO 为 Create React App 开启 PostCSS 新特性style.postcss.env 配置实战使用 CRACO 为 Create React App 开启 PostCSS 新特性style.postcss.env 配置实战 CRACOCreate R开发工具前端构建上一篇Conferences.digital播放进度跟踪如何实现跨会话的观看状态保存下一篇3种模式全面对比react-native-popover-view的RN Modal vs JS Modal vs Tooltip创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考