CleanWebpackPlugin清理构建目录

作者：陈川阅读数：31972人阅读分类：构建工具

CleanWebpackPlugin清理构建目录

CleanWebpackPlugin是webpack生态中一个常用的插件，主要用于在每次构建前清理输出目录。它能够自动删除之前构建生成的文件，确保输出目录始终保持最新状态，避免旧文件残留导致的问题。

为什么需要清理构建目录

在webpack构建过程中，输出目录可能会积累大量不再需要的文件。例如：

修改了输出文件名配置
移除了某些入口点
使用了hash/chunkhash/contenthash
切换了不同构建环境

如果不清理旧文件，可能会导致：

开发服务器加载了错误的旧资源
生产环境部署了多余的文件
构建分析工具显示不准确的数据
磁盘空间被无用文件占用

基本使用方法

首先需要安装插件：

npm install clean-webpack-plugin --save-dev

然后在webpack配置中引入并使用：

const { CleanWebpackPlugin } = require('clean-webpack-plugin');

module.exports = {
  // ...其他配置
  plugins: [
    new CleanWebpackPlugin()
  ]
};

配置选项详解

CleanWebpackPlugin提供了多个配置选项来满足不同需求：

dry

模拟删除操作，不会实际删除文件：

new CleanWebpackPlugin({
  dry: true  // 默认false
})

verbose

输出删除日志：

new CleanWebpackPlugin({
  verbose: true  // 默认false
})

cleanStaleWebpackAssets

自动删除webpack不再使用的资源：

new CleanWebpackPlugin({
  cleanStaleWebpackAssets: false  // 默认true
})

protectWebpackAssets

保护webpack当前正在使用的资源不被删除：

new CleanWebpackPlugin({
  protectWebpackAssets: false  // 默认true
})

cleanOnceBeforeBuildPatterns

指定在构建前要删除的文件模式：

new CleanWebpackPlugin({
  cleanOnceBeforeBuildPatterns: [
    '**/*',
    '!static-files*',
    '!directoryToPreserve/**'
  ]
})

dangerouslyAllowCleanPatternsOutsideProject

允许清理项目目录之外的文件（慎用）：

new CleanWebpackPlugin({
  dangerouslyAllowCleanPatternsOutsideProject: true  // 默认false
})

高级使用场景

多配置项目中的使用

在多配置webpack项目中，可以针对不同配置使用不同清理策略：

module.exports = [{
  name: 'client',
  output: {
    path: path.resolve(__dirname, 'dist/client')
  },
  plugins: [
    new CleanWebpackPlugin({
      cleanOnceBeforeBuildPatterns: ['**/*', '!shared/**']
    })
  ]
}, {
  name: 'server',
  output: {
    path: path.resolve(__dirname, 'dist/server')
  },
  plugins: [
    new CleanWebpackPlugin()
  ]
}];

保留特定文件

有时需要保留一些特殊文件（如README.md）：

new CleanWebpackPlugin({
  cleanOnceBeforeBuildPatterns: [
    '**/*',
    '!README.md',
    '!*.json'
  ]
})

自定义删除函数

可以通过自定义函数实现更复杂的清理逻辑：

new CleanWebpackPlugin({
  cleanAfterEveryBuildPatterns: ['static/**/*'],
  dangerouslyAllowCleanPatternsOutsideProject: true,
  beforeEmit: (compilation, patterns) => {
    console.log('即将清理以下文件:', patterns);
    return Promise.resolve();
  }
})

与其他插件的配合

与html-webpack-plugin配合

确保HTML文件被正确清理和重新生成：

plugins: [
  new CleanWebpackPlugin(),
  new HtmlWebpackPlugin({
    template: './src/index.html'
  })
]

与copy-webpack-plugin配合

处理静态资源复制时的清理问题：

plugins: [
  new CleanWebpackPlugin(),
  new CopyWebpackPlugin({
    patterns: [
      { from: 'public', to: 'assets' }
    ]
  })
]

常见问题解决

文件删除权限问题

在Windows系统上可能会遇到权限错误，可以尝试：

new CleanWebpackPlugin({
  cleanOnceBeforeBuildPatterns: ['**/*'],
  dangerouslyAllowCleanPatternsOutsideProject: true,
  dry: false,
  beforeEmit: async () => {
    await new Promise(resolve => setTimeout(resolve, 500));
  }
})

排除node_modules

避免意外删除依赖：

new CleanWebpackPlugin({
  cleanOnceBeforeBuildPatterns: [
    '**/*',
    '!node_modules/**'
  ]
})

处理符号链接

处理项目中的符号链接：

new CleanWebpackPlugin({
  handleSymlinks: true  // 默认false
})

性能优化建议

在开发模式下可以禁用插件提升构建速度：

plugins: [
  process.env.NODE_ENV === 'production' && new CleanWebpackPlugin()
].filter(Boolean)

对于大型项目，限制清理范围：

new CleanWebpackPlugin({
  cleanOnceBeforeBuildPatterns: ['js/**', 'css/**']
})

使用缓存避免重复清理：

new CleanWebpackPlugin({
  cleanOnceBeforeBuildPatterns: [],
  cleanAfterEveryBuildPatterns: ['tmp/**']
})

版本兼容性说明

不同版本的CleanWebpackPlugin有较大差异：

v1.x: 基本功能
v2.x: 引入更多配置选项
v3.x: 支持webpack 5
v4.x: 完全重构，API变化较大

建议查看对应版本的文档：

// v3.x及以下版本引入方式
const CleanWebpackPlugin = require('clean-webpack-plugin');

// v4.x+版本引入方式
const { CleanWebpackPlugin } = require('clean-webpack-plugin');

替代方案比较

除了CleanWebpackPlugin，还有其他清理方案：

使用rimraf手动清理：

// package.json
{
  "scripts": {
    "clean": "rimraf dist",
    "build": "npm run clean && webpack"
  }
}

使用shelljs插件：

const shell = require('shelljs');

class CleanPlugin {
  apply(compiler) {
    compiler.hooks.beforeRun.tap('CleanPlugin', () => {
      shell.rm('-rf', 'dist/*');
    });
  }
}

相比之下，CleanWebpackPlugin提供了：

更精细的文件模式控制
与webpack构建流程的深度集成
更好的跨平台兼容性
更安全的默认行为

实际项目中的最佳实践

区分环境配置：

const cleanOptions = {
  verbose: process.env.NODE_ENV !== 'production',
  dry: process.env.DRY_RUN === 'true',
  cleanOnceBeforeBuildPatterns: [
    '**/*',
    '!config.json',
    ...(process.env.NODE_ENV === 'development' ? ['!test-coverage/**'] : [])
  ]
};

plugins: [
  new CleanWebpackPlugin(cleanOptions)
]

多项目共享配置：

// shared-webpack-config.js
module.exports.cleanPlugin = (options = {}) => new CleanWebpackPlugin({
  cleanOnceBeforeBuildPatterns: ['**/*'],
  ...options
});

// webpack.config.js
const { cleanPlugin } = require('./shared-webpack-config');

module.exports = {
  plugins: [
    cleanPlugin({
      verbose: true
    })
  ]
};

与CI/CD集成：

new CleanWebpackPlugin({
  cleanOnceBeforeBuildPatterns: [
    '**/*',
    process.env.CI ? '!ci-lockfile.json' : '!.env.local'
  ]
})

插件内部机制解析

CleanWebpackPlugin的工作流程大致如下：

在webpack的beforeRun钩子注册清理任务
分析配置的文件模式
使用globby匹配文件
使用del库执行删除操作
处理可能出现的错误和警告
在afterEmit钩子执行后续清理（如果配置）

关键源码片段：

apply(compiler) {
  compiler.hooks.beforeRun.tapPromise(pluginName, () => this.handleInitial());
  compiler.hooks.watchRun.tapPromise(pluginName, () => this.handleInitial());
  compiler.hooks.afterEmit.tapPromise(pluginName, (compilation) => 
    this.handleAfterEmit(compilation));
}

async handleInitial() {
  const { remove, paths } = await this.getPaths();
  if (remove.length > 0) {
    await this.removeFiles(remove);
  }
  return { remove, paths };
}

自定义清理插件开发

如果需要更特殊的功能，可以基于CleanWebpackPlugin扩展：

class CustomCleanPlugin extends CleanWebpackPlugin {
  async handleAfterEmit(compilation) {
    await super.handleAfterEmit(compilation);
    // 自定义逻辑
    await this.removeFiles(['temp/*.log']);
  }
  
  async getPaths() {
    const result = await super.getPaths();
    return {
      ...result,
      remove: [...result.remove, 'extra-file.txt']
    };
  }
}

测试策略建议

为确保清理功能正常工作，建议：

单元测试验证文件模式匹配
集成测试检查实际文件系统变化
使用dry模式进行预检查
测试不同操作系统下的行为

示例测试代码：

describe('CleanWebpackPlugin', () => {
  it('should match correct files', async () => {
    const plugin = new CleanWebpackPlugin({
      cleanOnceBeforeBuildPatterns: ['**/*.js', '!vendor.js']
    });
    const { remove } = await plugin.getPaths();
    expect(remove).toContain('app.js');
    expect(remove).not.toContain('vendor.js');
  });
});

安全注意事项

永远不要配置dangerouslyAllowCleanPatternsOutsideProject: true除非绝对必要
避免使用../../等相对路径
生产环境部署前先在测试环境验证清理规则
保留重要文件的备份

错误示例：

// 危险配置！可能删除系统文件
new CleanWebpackPlugin({
  cleanOnceBeforeBuildPatterns: ['**/*'],
  dangerouslyAllowCleanPatternsOutsideProject: true
})

调试技巧

当清理行为不符合预期时：

启用verbose模式查看详细日志
使用dry运行模拟删除
检查文件模式是否正确定位到目标文件
验证当前工作目录是否正确

new CleanWebpackPlugin({
  verbose: true,
  dry: true,
  cleanOnceBeforeBuildPatterns: ['**/*.js']
})

做个网站！

本站部分内容来自互联网,一切版权均归源网站或源作者所有。

如果侵犯了你的权益请来信告知我们删除。邮箱：cc@cccx.cn

上一篇：HtmlWebpackPlugin自动生成HTML

下一篇：MiniCssExtractPlugin提取CSS

CleanWebpackPlugin清理构建目录