useless-files-webpack-plugin 用途及使用教程useless-files-webpack-pl

useless-files-webpack-plugin 用途及使用教程

✏️ 开篇说明 🎨

本文为全新原创插件教程，避开复杂理论，聚焦 useless-files-webpack-plugin 核心用法，主打「极简可复制、新手零门槛」，全程附实战代码+避坑提示，开发时直接抄作业，帮你快速掌握插件用法，有错欢迎指出来～

💡 核心目标：学会用该插件检测并删除webpack项目中「未被引用的无用文件」（如闲置图片、冗余CSS/JS、过期资源），减小打包体积、提升项目性能，避免无用文件占用空间。

📌 插件核心用途（必记！）

useless-files-webpack-plugin 是 webpack 生态中高频实用的「无用文件清理插件」，核心用途只有2个，精准解决项目痛点：

✅ 自动检测：遍历项目目录，精准识别「未被任何代码引用」的静态资源（图片、字体、CSS、JS、JSON等）。
✅ 一键清理：可配置「仅打印无用文件列表」或「自动删除无用文件」，无需手动查找删除，提升开发效率。

💡 适用场景：项目迭代中产生的闲置资源、多人协作遗留的无用文件、打包前的资源瘦身（尤其适合中大型项目）。

一、前置准备（新手必看）

该插件是 webpack 插件，需满足2个前置条件，否则无法使用：

1. 项目已集成 webpack（支持 webpack 4.x / 5.x，推荐5.x，兼容性更好）。
1. 项目使用 npm / yarn 管理依赖（需通过包管理器安装插件）。

⚠️ 提示：如果是 Vue CLI、Create React App 等脚手架项目，需先找到 webpack 配置文件（可手动暴露，后文实战会提）。

二、插件安装（1步搞定）

打开项目终端，执行以下命令安装插件（二选一，推荐npm），安装完成后自动加入项目依赖：


// 方式1：npm安装（推荐）
npm install useless-files-webpack-plugin --save-dev

// 方式2：yarn安装
yarn add useless-files-webpack-plugin --dev

💡 说明：--save-dev / --dev 表示「开发依赖」，仅在开发环境使用（打包、清理资源时生效），不影响生产环境。

三、核心使用教程（分2种场景，新手先学基础配置）

安装完成后，在 webpack 配置文件（webpack.config.js / webpack.prod.js）中引入并配置，分「基础配置」和「进阶配置」，按需选择。

1. 基础配置（新手首选，最常用）

核心功能：检测项目中未被引用的文件，打印文件列表，不自动删除（避免误删有用文件），适合首次使用、谨慎清理的场景。


// 1. 引入插件（webpack.config.js 顶部）
const UselessFilePlugin = require('useless-files-webpack-plugin');

// 2. 在 plugins 数组中配置插件（webpack.config.js 中 module.exports 内）
module.exports = {
  // 其他配置（entry、output、module等，不变）
  entry: './src/index.js',
  output: {
    filename: 'bundle.js',
    path: path.resolve(__dirname, 'dist')
  },
  module: {
    // 你的loader配置（如css-loader、file-loader等）
  },
  plugins: [
    // 基础配置：仅检测、打印无用文件，不删除
    new UselessFilePlugin({
      // 必写：需要检测的文件目录（通常是src目录，可多个）
      root: path.resolve(__dirname, 'src'),
      // 必写：需要检测的文件类型（数组形式，按需添加）
      glob: ['**/*.js', '**/*.css', '**/*.png', '**/*.jpg', '**/*.svg', '**/*.json'],
      // 可选：是否在终端打印无用文件列表（默认true，建议开启）
      log: true,
      // 可选：是否自动删除无用文件（默认false，新手不建议开启！）
      delete: false
    })
  ]
};

2. 进阶配置（按需使用，灵活定制）

核心功能：自定义排除无需检测的文件/目录、自动删除无用文件（谨慎使用），适合熟悉项目资源、需要批量清理的场景。


// 完整进阶配置示例（webpack.config.js）
const path = require('path');
const UselessFilePlugin = require('useless-files-webpack-plugin');

module.exports = {
  entry: './src/index.js',
  output: {
    filename: 'bundle.js',
    path: path.resolve(__dirname, 'dist')
  },
  plugins: [
    new UselessFilePlugin({
      root: path.resolve(__dirname, 'src'), // 检测根目录
      glob: ['**/*.js', '**/*.css', '**/*.png', '**/*.svg'], // 检测的文件类型
      log: true, // 打印无用文件列表
      delete: true, // 开启自动删除（谨慎！删除后无法恢复）
      // 进阶：排除无需检测的文件/目录（重点！避免误删配置文件、公共资源）
      exclude: [
        path.resolve(__dirname, 'src/assets/common'), // 排除公共资源目录
        path.resolve(__dirname, 'src/config'), // 排除配置文件目录
        '**/utils.js', // 排除所有目录下的utils.js（全局通用工具类）
        '**/*.d.ts' // 排除TS类型声明文件
      ]
    })
  ]
};

四、实战示例（可直接复制到项目中使用）

以「Vue CLI 5 项目」为例，完整演示插件的安装、配置、使用全过程（React项目/原生webpack项目可直接复用配置）：

步骤1：安装插件


// 进入Vue项目根目录，执行安装命令
npm install useless-files-webpack-plugin --save-dev

步骤2：暴露/创建webpack配置文件

Vue CLI 项目默认隐藏 webpack 配置，需手动创建「vue.config.js」（项目根目录），用于配置插件：


// vue.config.js（Vue CLI项目核心配置文件）
const path = require('path');
const UselessFilePlugin = require('useless-files-webpack-plugin');

// 配置webpack插件
module.exports = {
  configureWebpack: {
    plugins: [
      new UselessFilePlugin({
        root: path.resolve(__dirname, 'src'), // 检测src目录下的所有资源
        glob: [
          '**/*.js', '**/*.vue', '**/*.css', '**/*.scss',
          '**/*.png', '**/*.jpg', '**/*.svg'
        ], // 检测的文件类型（含Vue文件）
        log: true,
        delete: false, // 新手先关闭自动删除，确认无用文件后再开启
        // 排除Vue项目必要文件，避免误删
        exclude: [
          path.resolve(__dirname, 'src/main.js'), // 入口文件
          path.resolve(__dirname, 'src/App.vue'), // 根组件
          path.resolve(__dirname, 'src/router'), // 路由配置
          path.resolve(__dirname, 'src/store') // 状态管理
        ]
      })
    ]
  }
};

步骤3：运行检测命令

配置完成后，执行 webpack 打包命令，插件会自动检测并打印无用文件列表：


// 开发环境打包（检测无用文件）
npm run build:dev

// 生产环境打包（检测+可选删除）
npm run build

步骤4：查看结果并清理

1. 终端会打印所有未被引用的无用文件路径（如：src/assets/old-img.png、src/components/UnusedComponent.vue）。
1. 确认文件无用后，可将配置中的 delete 改为 true，重新执行打包命令，自动删除无用文件。
1. 清理完成后，再次打包，项目体积会明显减小（闲置资源越多，瘦身效果越明显）。

五、核心避坑（90%新手踩过，必看！）

🚨 避坑1：不要轻易开启 delete: true！首次使用务必先设为 false，打印列表确认无用文件后，再开启自动删除（删除后无法恢复）。
🚨 避坑2：必须配置 exclude 排除必要文件！比如入口文件、根组件、路由、配置文件、公共资源，否则会误删项目核心文件，导致项目报错。
🚨 避坑3：glob 配置要精准，不要检测 node_modules、dist 等目录（可通过 root 和 exclude 控制），否则会检测到大量无关文件。
🚨 避坑4：webpack 版本兼容！webpack 4.x 需使用插件 1.x 版本，webpack 5.x 需使用插件 2.x+ 版本，安装时注意版本匹配（安装失败可指定版本：npm install useless-files-webpack-plugin@2.0.0 --save-dev）。
🚨 避坑5：动态引用的文件会被误判！比如通过变量拼接路径引用的图片（如：imgUrl = ./assets/${name}.png），插件无法识别，会误判为无用文件，需在 exclude 中排除。

六、总结（重点提炼，快速记忆）

✅ 用途：检测并删除 webpack 项目中未被引用的无用文件，减小打包体积、提升性能。
✅ 核心步骤：安装插件 → 引入插件 → 配置检测目录/文件类型 → 运行检测 → 清理文件。
✅ 新手关键：delete 先设为 false，必配 exclude 排除核心文件，版本要和 webpack 匹配。
💡 小技巧：每次项目迭代完成、打包上线前，用该插件检测一次，避免无用资源占用服务器空间。