【免费下载链接】craco
Create React App Configuration Override, an easy and comprehensible configuration layer for Create React App.
本指南基于 use-ts-loader.md 配方,讲解如何通过
@craco/craco的 loader 工具函数,在 Create React App(CRA)项目中把负责编译 TypeScript / JavaScript 应用代码的babel-loader替换为ts-loader(以transpileOnly模式运行,类型检查仍交由fork-ts-checker-webpack-plugin负责),同时保留 babel-loader 处理非应用代码。读完本文,你将掌握getLoaders、removeLoaders、addAfterLoader、loaderByName、throwUnexpectedConfigError等 CRACO 核心工具函数的实际用法,并能独立完成"替换 CRA 默认 loader 链"这类高阶 Webpack 定制。
为什么需要替换 babel-loader 为 ts-loader
CRA(react-scripts)默认使用 babel-loader 编译项目中的所有 TypeScript / JavaScript 代码,类型检查则由独立的 fork-ts-checker-webpack-plugin 在编译之外并行执行。这种"babel 转译 + fork-ts-checker 类型检查"的组合是 CRA 的官方方案,但在某些场景下开发者希望改用 ts-loader:
- 希望由 TypeScript 编译器(
tsc)直接参与转译,获得与tsconfig.json更一致的编译行为; - 需要借助 ts-loader 的
transpileOnly模式把转译与类型检查彻底解耦,构建速度更快; - 需要对应用代码的编译管线做更精细的定制(例如自定义 ts-loader 的
options)。
CRACO 提供的 webpack.configure 钩子接收完整的 Webpack 配置对象,允许你以编程方式增删 loader。本配方正是利用这一能力,在 craco.config.js 中完成一次"手术式"替换:移除所有 babel-loader,为应用代码装上 ts-loader,再把 babel-loader 请回来处理非应用代码。
在动手之前,请先确认项目已经安装 ts-loader 依赖(例如 npm install ts-loader --save-dev),否则 require.resolve('ts-loader') 会解析失败。
完整配置:craco.config.js
以下是本配方在 craco.config.js 中的完整实现(与 use-ts-loader.md 中的示例一致,并补充了逐步解读):
// 本配方将 babel-loader 对 TypeScript / JavaScript 应用代码的编译
// 替换为以 transpileOnly 模式运行的 ts-loader(类型检查仍由
// fork-ts-checker-webpack-plugin 执行)。如需进一步定制 ts-loader,
// 可调整下方 options。babel-loader 仍被用于加载非应用代码
// (如 node_modules 中的 JS)。使用前请确保 package.json 中已添加 ts-loader 依赖。
const {
addAfterLoader,
removeLoaders,
loaderByName,
getLoaders,
throwUnexpectedConfigError,
} = require('@craco/craco');
const throwError = (message) =>
throwUnexpectedConfigError({
packageName: 'craco',
githubRepo: 'gsoft-inc/craco',
message,
githubIssueQuery: 'webpack',
});
module.exports = {
webpack: {
configure: (webpackConfig, { paths }) => {
// 第一步:定位所有 babel-loader 实例
const { hasFoundAny, matches } = getLoaders(
webpackConfig,
loaderByName('babel-loader')
);
if (!hasFoundAny) throwError('failed to find babel-loader');
// 第二步:移除全部 babel-loader
console.log('removing babel-loader');
const { hasRemovedAny, removedCount } = removeLoaders(
webpackConfig,
loaderByName('babel-loader')
);
if (!hasRemovedAny) throwError('no babel-loader to remove');
if (removedCount !== 2)
throwError('had expected to remove 2 babel loader instances');
// 第三步:为应用代码添加 ts-loader
console.log('adding ts-loader');
const tsLoader = {
test: /\.(js|mjs|jsx|ts|tsx)$/,
include: paths.appSrc,
loader: require.resolve('ts-loader'),
options: { transpileOnly: true },
};
const { isAdded: tsLoaderIsAdded } = addAfterLoader(
webpackConfig,
loaderByName('url-loader'),
tsLoader
);
if (!tsLoaderIsAdded) throwError('failed to add ts-loader');
console.log('added ts-loader');
// 第四步:把 babel-loader 加回非应用代码的编译位置
console.log('adding non-application JS babel-loader back');
const { isAdded: babelLoaderIsAdded } = addAfterLoader(
webpackConfig,
loaderByName('ts-loader'),
matches[1].loader // babel-loader
);
if (!babelLoaderIsAdded)
throwError('failed to add back babel-loader for non-application JS');
console.log('added non-application JS babel-loader back');
return webpackConfig;
},
},
};
配置逐段拆解
1. 从 @craco/craco 引入 loader 工具函数
const {
addAfterLoader,
removeLoaders,
loaderByName,
getLoaders,
throwUnexpectedConfigError,
} = require('@craco/craco');
这些工具函数全部从 @craco/craco 包的主入口导出,其实现位于 packages/craco/src/lib/loaders.ts,并在 packages/craco/src/index.ts 中被统一 re-export。除此之外,同族函数还包括 getLoader、addBeforeLoader、addBeforeLoaders、addAfterLoaders,可参考 Webpack Loaders 文档。
2. 包装统一错误抛出逻辑
const throwError = (message) =>
throwUnexpectedConfigError({
packageName: 'craco',
githubRepo: 'gsoft-inc/craco',
message,
githubIssueQuery: 'webpack',
});
throwUnexpectedConfigError 由 CRACO 提供(实现见 packages/craco/src/lib/plugin-utils.ts),它会抛出一个包含详尽排障指引的 Error:
- 提示错误可能源于 react-scripts 或 craco 升级,并给出
yarn upgrade craco/npm update craco的更新建议; - 根据
githubIssueQuery拼接 GitHub Issue 搜索链接(本配方传入'webpack'),引导开发者检索 craco 与 create-react-app 仓库中的相关问题。
这意味着当 CRA 内部 webpack 配置结构发生变化、loader 数量或命名不再符合预期时,配置会立即以可诊断的错误信息失败,而不是静默地生成错误构建产物。
3. webpack.configure 钩子与 paths 上下文
webpack: {
configure: (webpackConfig, { paths }) => { ... }
}
webpack.configure 是 CracoWebpackConfig 中最灵活的配置项,既可以是对象(内部用 webpack-merge 浅合并),也可以是函数。当为函数时,CRACO 会在 merge-webpack-config.ts 的 giveTotalControl 中调用它:传入已应用完 babel、eslint、style、typescript 等内置 override 后的完整 webpack 配置,以及 WebpackContext 上下文,函数的返回值将直接作为最终配置(返回 undefined 会抛出错误)。
上下文中的 paths 即 CRA 的 paths 对象(类型定义见 packages/craco-types/src/context.ts 中的 CraPaths 接口)。本配方使用的 paths.appSrc 指向应用源码目录(即 src/),它保证了 ts-loader 的 include 只覆盖应用代码。
由于 configure 在 mergeWebpackConfig 的调用链中处于最后阶段,你可以在这里对 webpack 配置做任何程度的"深度手术",这正是本配方的操作基础。
4. 定位 babel-loader:getLoaders + loaderByName
const { hasFoundAny, matches } = getLoaders(
webpackConfig,
loaderByName('babel-loader')
);
if (!hasFoundAny) throwError('failed to find babel-loader');
loaderByName('babel-loader') 返回一个 LoaderMatcher 函数。从 loaders.ts 源码可以看出,它的匹配逻辑是:对 rule 的 loader 字段(或字符串形式的 rule)检查是否包含 ${path.sep}babel-loader${path.sep} 或 @babel-loader${path.sep} 这样的路径片段,从而能同时命中"以文件名结尾"和"以 scoped 包名形式"引用的 loader,且不误伤 babel-loader 之外名称相近的其他 loader。
getLoaders 会递归遍历 webpackConfig.module.rules,包括 rule.use 数组、rule.oneOf 分支以及数组形式的 rule.loader,返回所有匹配项;每个匹配项结构为 { loader, parent, index },其中 parent 是包含该 loader 的规则数组,index 是其在数组中的下标——这两个字段是后续"插入"操作的关键。如果 CRA 配置里一个 babel-loader 都没找到(例如 react-scripts 版本结构变化),hasFoundAny 为 false,配置立即报错。
5. 移除 babel-loader:removeLoaders
console.log('removing babel-loader');
const { hasRemovedAny, removedCount } = removeLoaders(
webpackConfig,
loaderByName('babel-loader')
);
if (!hasRemovedAny) throwError('no babel-loader to remove');
if (removedCount !== 2)
throwError('had expected to remove 2 babel loader instances');
removeLoaders 同样递归遍历所有规则,把所有匹配到的 loader 从 parent 数组中 splice 掉,并返回 { hasRemovedAny, removedCount }。
本配方硬性断言必须恰好移除 2 个 babel-loader 实例:CRA 的 webpack 配置中,babel-loader 通常同时出现在"应用代码规则"和"非应用代码(node_modules 中的 JS)规则"两处。如果移除数量不等于 2,说明 react-scripts 的默认配置结构已经与配方假设不符,此时宁可报错也不应继续——这是一种非常典型的"防御式配置"写法。
6. 添加 ts-loader:addAfterLoader
const tsLoader = {
test: /\.(js|mjs|jsx|ts|tsx)$/,
include: paths.appSrc,
loader: require.resolve('ts-loader'),
options: { transpileOnly: true },
};
const { isAdded: tsLoaderIsAdded } = addAfterLoader(
webpackConfig,
loaderByName('url-loader'),
tsLoader
);
if (!tsLoaderIsAdded) throwError('failed to add ts-loader');
新 loader 规则覆盖 js、mjs、jsx、ts、tsx 五种扩展名,include: paths.appSrc 限定只处理应用源码。options.transpileOnly: true 让 ts-loader 只做转译、不做类型检查——因为类型检查仍然由 CRA 内置的 fork-ts-checker-webpack-plugin 在后台并行执行,避免重复检查拖慢构建。
addAfterLoader(webpackConfig, matcher, newLoader) 会先找到第一个匹配 url-loader 的 loader,然后在其 parent 数组的 index + 1 位置插入新 loader(见 loaders.ts 中 addLoader 的实现:positionAdapter 为 (x) => x + 1 即"之后",为 (x) => x 即"之前")。如果连 url-loader 都找不到,isAdded 为 false,配置报错。选择挂在 url-loader 之后,是为了确保 ts-loader 在应用代码规则链中处于正确位置。
7. 把 babel-loader 加回非应用代码
const { isAdded: babelLoaderIsAdded } = addAfterLoader(
webpackConfig,
loaderByName('ts-loader'),
matches[1].loader // babel-loader
);
if (!babelLoaderIsAdded)
throwError('failed to add back babel-loader for non-application JS');
这一步是整个配方的点睛之笔:matches[1].loader 是从第 4 步 getLoaders 结果中取出的第二个 babel-loader 实例(原始引用)。在移除阶段,两个 babel-loader 都已被从规则数组中删除,但它们的对象引用仍保存在 matches 中;现在把它们(作为 loader rule)重新插入到刚添加的 ts-loader 之后。
这样做的意义在于:应用代码交给 ts-loader 编译后,babel-loader 仍被用于编译非应用代码——CRA 中这部分通常指 node_modules 里的第三方 JavaScript(它们走 babel-preset-react-app 的转译,但不属于 paths.appSrc 范围,因此不会被 ts-loader 的 include 拦截)。
8. 返回修改后的配置
return webpackConfig;
webpack.configure 函数必须返回 webpack 配置对象。根据 merge-webpack-config.ts 的 giveTotalControl 实现,返回 undefined 或空值会抛出 "craco: 'webpack.configure' function didn't returned a webpack config object." 错误。
运行预期与日志输出
保存 craco.config.js 后,正常执行 npm start 或 npm run build(脚本需替换为 craco,可参考 Getting Started),终端会依次打印本配方埋下的日志:
removing babel-loader
adding ts-loader
added ts-loader
adding non-application JS babel-loader back
added non-application JS babel-loader back
如果其中任何一步与 CRA 默认配置结构不符(例如找不到 babel-loader、移除数量不等于 2、找不到 url-loader 等),都会触发 throwUnexpectedConfigError,给出可定位问题的错误信息。这类"显式失败"设计在 CRACO 的 loader 工具链中贯穿始终——从 loaders.ts 的实现可以看到,每个操作都以 hasFoundAny / hasRemovedAny / isAdded 这样的布尔结果回传,把"配置结构假设"的校验责任交还给使用者。
与 fork-ts-checker 的联动:transpileOnly 的前提
本配方把类型检查完全托付给 fork-ts-checker-webpack-plugin,这与 ts-loader 的 transpileOnly: true 是配套设计。如果你希望彻底关闭类型检查(例如临时快速验证),CRACO 还提供了更直接的内置开关:在 craco.config.js 中设置 typescript.enableTypeChecking: false,即可移除 ForkTsCheckerWebpackPlugin(实现见 packages/craco/src/lib/features/webpack/typescript.ts)。两者的区别在于:
- 本配方:保留类型检查,仅替换转译器(ts-loader + transpileOnly);
enableTypeChecking: false:关闭类型检查,babel-loader 保持不变。
如果你的诉求只是"换掉转译器但不想丢类型检查",本配方是正确选择;如果诉求是"构建时不要类型检查",则内置开关更简单。
版本与适用前提
- 本配方假定当前项目的 react-scripts(CRA)版本符合 CRACO 支持的版本范围(packages/craco/src/lib/cra.ts 中
CRA_LATEST_SUPPORTED_MAJOR_VERSION = '5.0.0',表示最低支持 5.0.0 及以上主版本)。 - 配方中"恰好移除 2 个 babel-loader"的断言与 CRA 内部 loader 结构强相关。如果后续 react-scripts 调整了 loader 布局,
removedCount !== 2的检查会先于任何构建失败暴露问题——这正是该防御式写法的价值。 - ts-loader 属于第三方依赖,不在 CRACO 或 CRA 的依赖树中,使用前务必在项目的
package.json中显式安装。
延伸阅读
- 本文配方的原始出处:use-ts-loader.md
- Loader 工具函数 API 详解:Webpack Loaders
webpack.configure配置项说明:Webpack Configuration- 工具函数源码:packages/craco/src/lib/loaders.ts
- 错误抛出工具源码:packages/craco/src/lib/plugin-utils.ts
- 上下文类型定义:packages/craco-types/src/context.ts
【免费下载链接】craco
Create React App Configuration Override, an easy and comprehensible configuration layer for Create React App.
创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考



