使用 ts-loader 替换 babel-loader:CRACO 应用代码编译管线改造实战

  • 开发工具
  • 前端构建

【免费下载链接】craco

Create React App Configuration Override, an easy and comprehensible configuration layer for Create React App.

项目地址: https://gitcode.com/gh_mirrors/cr/craco
点击查看 免费下载

本指南基于 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 中显式安装。

延伸阅读

  • 开发工具
  • 前端构建

【免费下载链接】craco

Create React App Configuration Override, an easy and comprehensible configuration layer for Create React App.

项目地址: https://gitcode.com/gh_mirrors/cr/craco
点击查看 免费下载

创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考

实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值
⌂ 换网址