如何解决Node.js+Rollup.js中npm工作区的循环依赖问题

问题背景 #

将项目从Yarn切换为带工作区的NPM，并把Node.js版本从12升级到16（也试过14）后，原本正常的CLI工具用Rollup构建时出现Node库循环依赖，运行构建产物时报错：TypeError: util.inherits is not a function

相关配置 #

package.json #

{
  "devDependencies": {
    "@rollup/plugin-commonjs": "22.0.1",
    "@rollup/plugin-node-resolve": "13.3.0",
    "@rollup/plugin-typescript": "8.3.3",
    "@types/node": "^16.11.9",
    "rollup": "2.77.0",
    "rollup-plugin-node-externals": "4.1.1",
    "tslib": "2.4.0",
    "typescript": "4.7.4",
    "watch": "1.0.2"
  },
  "dependencies": {
    "commander": "9.4.0",
    "execa": "^6.1.0"
  }
}

rollup.config.js #

import typescript from '@rollup/plugin-typescript';
import commonjs from '@rollup/plugin-commonjs';
import { nodeResolve } from '@rollup/plugin-node-resolve';
import externals from 'rollup-plugin-node-externals';

export default {
  input: 'src/csa.ts',
  output: {
    dir: 'build',
    format: 'cjs',
    strict: false,
    banner: '#! /usr/bin/env node\n',
  },
  plugins: [typescript(), commonjs({ transformMixedEsModules: true }), nodeResolve({ preferBuiltins: true }), externals()],
};

构建日志 #

src/csa.ts → build...
(!) Circular dependencies
../../node_modules/util/util.js -> ../../node_modules/util/node_modules/inherits/inherits.js -> ../../node_modules/util/util.js
../../node_modules/assert/node_modules/util/util.js -> ../../node_modules/assert/node_modules/inherits/inherits.js -> ../../node_modules/assert/node_modules/util/util.js
created build in 3.6s

运行报错 #

/Users/me/apps/hrh/csa/packages/cli/build/csa.js:6795
    util.inherits(assert.AssertionError, Error);
         ^

TypeError: util.inherits is not a function
    at requireAssert (/Users/me/apps/hrh/csa/packages/cli/build/csa.js:6795:7)
    at Object.<anonymous> (/Users/me/apps/hrh/csa/packages/cli/build/csa.js:7231:16)
    at Module._compile (node:internal/modules/cjs/loader:1105:14)
    at Object.Module._extensions..js (node:internal/modules/cjs/loader:1159:10)
    at Module.load (node:internal/modules/cjs/loader:981:32)
    at Function.Module._load (node:internal/modules/cjs/loader:822:12)
    at Function.executeUserEntryPoint [as runMain] (node:internal/modules/run_main:77:12)
    at node:internal/main/run_main_module:17:47

解决方案 #

问题根源 #

项目依赖中混入了第三方util包（并非Node.js内置的util模块），这个包和内置模块冲突，且自身存在循环依赖，导致Rollup打包时错误地将第三方util打包进产物，而该包的inherits方法未正确导出或存在兼容问题。

具体修复步骤 #

1. 排查依赖树
   执行命令查看哪个依赖引入了第三方util：

   npm ls util
   

   找到后可以尝试升级该依赖，或者通过npm dedupe扁平化依赖树，避免嵌套的util包。

2. 调整Rollup配置，强制使用内置模块
   修改rollup.config.js，确保util和assert这类Node内置模块被正确排除，不被打包进产物：

   import typescript from '@rollup/plugin-typescript';
   import commonjs from '@rollup/plugin-commonjs';
   import { nodeResolve } from '@rollup/plugin-node-resolve';
   import externals from 'rollup-plugin-node-externals';
   
   export default {
     input: 'src/csa.ts',
     output: {
       dir: 'build',
       format: 'cjs',
       strict: false,
       banner: '#! /usr/bin/env node\n',
     },
     plugins: [
       externals({
         builtins: true, // 自动排除所有Node内置模块
         deps: true
       }),
       typescript(),
       commonjs({ 
         transformMixedEsModules: true,
         namedExports: {
           'util': ['inherits']
         }
       }),
       nodeResolve({ 
         preferBuiltins: true,
         exclude: ['node_modules/util/**']
       })
     ],
     external: ['util', 'assert']
   };
   

3. 清理依赖重新安装
   删除node_modules和package-lock.json后重新安装：

   rm -rf node_modules package-lock.json
   npm install
   

验证 #

重新执行Rollup构建命令，确认循环依赖提示消失，运行产物不再出现util.inherits is not a function报错。

内容的提问来源于stack exchange，提问作者kokokenada