循环依赖插件(Circular Dependency Plugin)用户手册

循环依赖插件(Circular Dependency Plugin)用户手册

circular-dependency-plugin Detect circular dependencies in modules compiled with Webpack 项目地址: https://gitcode.com/gh_mirrors/ci/circular-dependency-plugin

---

循环依赖插件在使用webpack进行模块打包时，能够帮助开发者识别出循环依赖的模块。尽管在复杂软件工程中循环依赖有时是不可避免的，并不总意味着错误，但在疑似有bug的情形下，此插件极其有用以定位问题。

安装指南

要开始使用Circular Dependency Plugin，首先需要通过npm或yarn将其添加到您的项目中：

npm install --save circular-dependency-plugin

对于TypeScript用户，确保也安装对应的类型定义：

npm install --save-dev @types/circular-dependency-plugin

项目使用说明

基础用法

在您的webpack.config.js文件中，引入并配置该插件如下：

const CircularDependencyPlugin = require('circular-dependency-plugin');

module.exports = {
  entry: "./src/index",
  plugins: [
    new CircularDependencyPlugin({
      exclude: /a\.js|node_modules/, // 排除特定文件或目录的检查
      include: /dir/, // 指定需要特别检查的文件或目录
      failOnError: true, // 遇到循环依赖时是否当作错误处理
      allowAsyncCycles: false, // 是否允许异步循环
      cwd: process.cwd(), // 设置工作目录来展示模块路径
    }),
  ],
};

高级用法

您可以通过监听插件的不同生命周期方法实现更复杂的逻辑，例如计数循环依赖并在超过预设值时失败构建：

const MAX_CYCLES = 5;
let numCyclesDetected = 0;

module.exports = {
  entry: "./src/index",
  plugins: [
    new CircularDependencyPlugin({
      onStart({ compilation }) { numCyclesDetected = 0; }, // 初始化计数
      onDetected({ module: webpackModuleRecord, paths, compilation }) {
        numCyclesDetected++;
        compilation.warnings.push(new Error(paths.join(' -> ')));
      },
      onEnd({ compilation }) {
        if (numCyclesDetected > MAX_CYCLES) {
          compilation.errors.push(new Error(`超出最大循环依赖限制 (${MAX_CYCLES})`));
        }
      },
    }),
  ],
};

项目API使用文档

• exclude: {RegExp} 不检查匹配此正则的文件。
• include: {RegExp} 仅检查匹配此正则的文件。
• failOnError: {boolean} 设置为true时，循环依赖会导致构建失败。
• allowAsyncCycles: {boolean} 允许异步循环，默认false。
• cwd: {string} 设置当前工作目录，用于显示模块路径。

项目安装方式（已包含于上方“安装指南”）

只需一行命令即可将Circular Dependency Plugin集成至您的项目：

npm i circular-dependency-plugin

确保在应用此插件前，您的环境已准备好webpack相应版本的支持。

---

此文档旨在提供全面指导，帮助您有效利用Circular Dependency Plugin识别和管理项目中的循环依赖问题，从而提升代码质量和可维护性。遇到问题或有改进意见时，欢迎提交GitHub上的Issues。

circular-dependency-plugin Detect circular dependencies in modules compiled with Webpack 项目地址: https://gitcode.com/gh_mirrors/ci/circular-dependency-plugin