eslint-rspack-plugin 5.0.0 转向纯 ESM：升级配置与构建性能取舍

预计阅读时间：7 分钟

eslint-rspack-plugin 5.0.0 已改为纯 ESM 包，并移除 CommonJS 构建产物。这次调整让插件与 Rstack 生态的模块方向保持一致，但也意味着仍在使用 require() 或 CommonJS 配置文件的项目不能只升级版本而不检查构建配置。

插件的核心职责没有改变：在 Rspack 构建过程中运行 ESLint。真正需要团队做决定的是，lint 应该继续阻塞每次构建，还是拆成独立命令交给编辑器、Git hooks 和 CI 执行。

纯 ESM 会影响哪些配置

如果项目已经使用 rspack.config.mjs，或者 package.json 中声明了 "type": "module"，升级通常比较直接。仍使用 rspack.config.cjs 和 require() 的项目则需要迁移插件加载方式。

旧式 CommonJS 配置可能类似：

const ESLintRspackPlugin = require('eslint-rspack-plugin');

module.exports = {
  plugins: [new ESLintRspackPlugin()],
};

5.0.0 不再提供 CommonJS 构建，因此不能继续假设 require() 能直接加载插件。可以这样实践：将 Rspack 配置改为 ESM，并通过 import 引入插件。

先安装指定主版本：

npm install --save-dev eslint-rspack-plugin@^5.0.0

然后创建或调整 rspack.config.mjs：

import ESLintRspackPlugin from 'eslint-rspack-plugin';

export default {
  entry: './src/index.js',
  plugins: [
    new ESLintRspackPlugin({
      extensions: ['js', 'jsx', 'ts', 'tsx'],
    }),
  ],
};

这里的插件选项应以项目实际使用的 5.x API 和现有配置为准；示例重点是把配置入口改为 ESM。迁移时还要检查配置文件中的其他依赖，因为某些 CommonJS 插件在 ESM 文件中可能需要不同的导入写法。

如果整个 Node.js 项目都准备采用 ESM，也可以在 package.json 中声明模块类型：

{
  "type": "module",
  "scripts": {
    "build": "rspack build"
  }
}

这会影响项目内所有 .js 文件的模块解释方式，改动范围通常大于只把配置重命名为 .mjs。对于仍有大量 CommonJS 脚本的仓库，单独使用 rspack.config.mjs 往往更容易控制风险。

把 ESLint 放进构建链意味着什么

构建插件的优势很直接：开发者运行构建时不会漏掉 lint，错误也能进入统一的构建输出。在小型项目或需要强制本地反馈的团队中，这种约束很实用。

代价是 ESLint 会占用构建时间。源码规模、规则复杂度、TypeScript 类型感知规则和文件扫描范围都会放大开销。如果插件在开发服务器的每次重新编译中运行，代码改动到页面刷新的反馈周期也可能变长。

因此，是否保留构建集成不应只看“能不能运行”，还应测量以下指标：

冷启动构建耗时与启用插件前后的差值；
修改单个文件后的增量构建耗时；
lint 是否扫描生成目录、缓存目录或不相关工作区；
CI 中是否已经存在重复的 ESLint 步骤；
lint 失败是否必须阻止开发构建，还是只需阻止合并。

更快的做法：将 lint 拆成独立任务

对于构建频繁或代码量较大的项目，可以这样实践：从 Rspack 插件列表中移除 ESLint 集成，改用独立脚本并启用 ESLint 缓存。

{
  "type": "module",
  "scripts": {
    "dev": "rspack serve",
    "build": "rspack build",
    "lint": "eslint src --cache --cache-location .cache/eslint",
    "lint:ci": "eslint src --max-warnings=0"
  }
}

本地开发时分别执行：

npm run dev
npm run lint

CI 中则可以并行执行构建和 lint。下面以 GitHub Actions 为例；其他 CI 平台可以采用相同的任务拆分思路：

name: verify

on:
  pull_request:
  push:
    branches: [main]

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm
      - run: npm ci
      - run: npm run lint:ci
      - run: npm run build

这种方式让 rspack serve 专注于编译和热更新，同时仍由 CI 保证不合规代码无法合并。为了缩短本地反馈时间，还可以让编辑器 ESLint 扩展检查当前文件，或在提交前只检查暂存文件。

升级时不要只验证“可以安装”

建议在独立分支中完成 5.0.0 升级，并按以下清单验证：

将对插件的 require() 调用改为 ESM import；
明确选择 .mjs 配置文件或项目级 "type": "module"；
检查 Rspack 配置引用的其他模块是否兼容 ESM；
执行一次生产构建和一次开发服务器增量构建；
对比启用与禁用插件时的构建耗时；
确认 CI 中不存在无意义的重复 lint；
确认 lint 失败策略符合团队的合并规则。

纯 ESM 是这次版本升级最明确的兼容性边界。对已经采用 ESM 的 Rstack 项目，它主要是依赖升级；对仍以 CommonJS 为主的项目，它则是一次配置迁移。至于 ESLint 是否继续嵌入构建流程，应由实际性能数据和团队工作流决定，而不是由插件是否可用决定。

eslint-rspack-plugin 5.0.0 转向纯 ESM：升级配置与构建性能取舍

纯 ESM 会影响哪些配置

把 ESLint 放进构建链意味着什么

更快的做法：将 lint 拆成独立任务

升级时不要只验证“可以安装”

相关推荐

建议反馈