本教程详细阐述如何使用 webpack 5 高效配置前端项目，以同时生成 javascript 和 css 文件的压缩版（.min）和非压缩版。我们将重点介绍 minicssextractplugin 和自定义 minimizer 的应用，解决常见的输出冲突问题，并优化构建流程，确保输出资源的准确性和可用性。
1. 理解需求：为何需要同时生成压缩与非压缩资源？
在现代前端开发中，同时生成资源的压缩版（例如 template.min.js、template.min.css）和非压缩版（例如 template.js、template.css）是一种常见且推荐的做法。这种策略带来了多方面的好处：
- 生产环境优化： 压缩版文件体积更小，加载速度更快，有助于提升用户体验和网站性能。
- 开发与调试便利： 非压缩版文件包含完整的代码和可读的格式，便于开发者在开发过程中进行调试和问题排查。同时，通常会为非压缩版生成 Source Map，进一步简化调试。
- 灵活部署： 允许根据部署环境（开发、测试、生产）灵活选择使用不同版本的资源。
- CDN 缓存： 某些 CDN 可能对不同文件版本有不同的缓存策略，提供多种版本可以更好地适应这些需求。
本教程将以一个 Joomla 4 模板项目为例，指导您如何使用 Webpack 5 实现这一目标。
2. 核心挑战与解决方案概述
在 Webpack 中同时生成同一源文件的压缩与非压缩版本，尤其是对于 CSS 文件，可能会遇到以下挑战：
- 输出文件冲突： 如果配置不当，Webpack 可能会尝试将多个入口点编译到相同的输出文件名，导致构建失败。
- CSS 处理复杂性： CSS 文件不像 JavaScript 那样可以直接通过 Webpack 的默认优化器处理。需要专门的插件来提取 CSS 并进行优化。
- 不正确的输出格式： 未经正确配置，Webpack 可能会将 CSS 文件输出为 JavaScript 模块，而不是纯 CSS 文件。
为解决这些问题，我们将采用以下关键工具和策略：
立即学习“前端免费学习笔记（深入）”；
- MiniCssExtractPlugin： 专门用于将 CSS 从 JavaScript bundle 中提取到单独的 .css 文件中。
- TerserPlugin： Webpack 5 默认的 JavaScript 压缩器，我们可以通过配置其 include 选项来有选择地压缩文件。
- CssMinimizerPlugin： 针对 CSS 文件的专业压缩器，同样可以通过 include 选项进行精细控制。
- 清晰的入口点命名： 通过在 entry 配置中为压缩和非压缩版本使用不同的名称后缀（如 .min），配合 output.filename 和 MiniCssExtractPlugin.filename 中的 [name] 占位符，实现灵活的文件命名。
3. Webpack 配置详解
以下是实现上述目标的 webpack.config.js 详细配置步骤。
3.1 项目结构与依赖安装
首先，确保您的项目具有以下基本结构，并且已安装必要的 Webpack 及其相关插件：
your-project/ ├── src/ │ ├── js/ │ │ └── template.js │ ├── scss/ │ │ └── template.scss │ ├── index.php │ ├── joomla.asset.json │ ├── templateDetails.xml │ └── images/ ├── dist/ (构建输出目录) ├── webpack.config.js └── package.json
安装所需依赖：
npm install -D webpack webpack-cli copy-webpack-plugin terser-webpack-plugin css-minimizer-webpack-plugin mini-css-extract-plugin sass sass-loader css-loader
3.2 Webpack 配置文件 webpack.config.js
const path = require('path');
const CopyPlugin = require('copy-webpack-plugin');
const TerserPlugin = require("terser-webpack-plugin");
const CssMinimizerPlugin = require("css-minimizer-webpack-plugin");
const MiniCssExtractPlugin = require("mini-css-extract-plugin");
const dist_path = path.resolve(__dirname, 'dist');
const media_root_path = 'media/templates/site/tofu'; // Joomla 模板的媒体根路径
module.exports = {
// devtool: 'source-map', // 可选：启用 Source Map 以便调试
// 1. 入口 (Entry) 配置
entry: {
'js/template': './src/js/template.js', // 非压缩 JS
'js/template.min': './src/js/template.js', // 压缩 JS
'css/template': './src/scss/template.scss', // 非压缩 CSS
'css/template.min': './src/scss/template.scss',// 压缩 CSS
},
// 2. 输出 (Output) 配置
output: {
path: dist_path,
// 对于 JS 文件，使用 [name].js 格式，[name] 会根据 entry 中的键生成
filename: `${media_root_path}/[name].js`,
},
// 3. 模块规则 (Module Rules)
module: {
rules: [
{
test: /\.js$/,
exclude: /node_modules/,
use: [], // 如果需要 Babel 转译，可以在这里添加 'babel-loader'
},
{
test: /\.s[ac]ss$/i, // 匹配 .scss 或 .sass 文件
use: [
// 提取 CSS 到单独文件，而不是注入到 JS 中
MiniCssExtractPlugin.loader,
// 解析 CSS 中的 @import 和 url()
"css-loader",
{
// 编译 Sass 到 CSS
loader: "sass-loader",
options: {
implementation: require("sass"), // 推荐使用 dart-sass
sassOptions: {
outputStyle: 'expanded' // 确保 Sass 编译为非压缩格式，后续由 CssMinimizerPlugin 处理压缩
}
},
},
],
},
],
},
// 4. 优化 (Optimization) 配置
optimization: {
minimize: true, // 启用最小化
minimizer: [
// JS 压缩器，只对名称中包含 '.min.js' 的文件进行压缩
new TerserPlugin({
include: /\.min\.js$/
}),
// CSS 压缩器，只对名称中包含 '.min.css' 的文件进行压缩
new CssMinimizerPlugin({
include: /\.min\.css$/
})
],
},
// 5. 插件 (Plugins) 配置
plugins: [
// 复制静态文件
new CopyPlugin({
patterns: [
{ from: path.resolve(__dirname, 'src/index.php'), to: path.resolve(dist_path, 'index.php') },
{ from: path.resolve(__dirname, 'src/joomla.asset.json'), to: path.resolve(dist_path, 'joomla.asset.json') },
{ from: path.resolve(__dirname, 'src/templateDetails.xml'), to: path.resolve(dist_path, 'templateDetails.xml') },
{ from: path.resolve(__dirname, 'src/images'), to: path.resolve(dist_path, media_root_path, 'images') },
],
}),
// 提取 CSS 文件，并使用 [name].css 格式输出
new MiniCssExtractPlugin({
filename: `${media_root_path}/[name].css`,
})
],
// 6. 统计信息配置 (可选)
stats: {
loggingDebug: ['sass-loader']
},
};3.3 配置解析
-
入口 (Entry) 配置：
- 我们为 template.js 和 template.scss 各定义了两个入口点：一个用于生成非压缩版本（js/template, css/template），另一个用于生成压缩版本（js/template.min, css/template.min）。
- [name] 占位符在 output.filename 和 MiniCssExtractPlugin.filename 中会根据这些入口点的键值进行替换。
-
输出 (Output) 配置：
- path: 指定所有输出文件的根目录。
- filename: 定义 JavaScript 文件的输出命名规则。[name].js 会确保 js/template 生成 template.js，js/template.min 生成 template.min.js。请注意，这个 filename 主要影响 JS 文件的输出。
-
模块规则 (Module Rules)：
- JavaScript 规则： 简单的规则，排除 node_modules。如果您需要对 JS 进行转译（如 ES6 到 ES5），可以在 use 数组中添加 babel-loader。
-
SCSS/CSS 规则：
- MiniCssExtractPlugin.loader: 这是将 CSS 从 JS bundle 中分离出来的关键。它将 CSS 视为一个独立的资源。
- css-loader: 解释 CSS 文件中的 @import 和 url() 语句。
- sass-loader: 将 Sass/SCSS 代码编译为纯 CSS。sassOptions: { outputStyle: 'expanded' } 确保 Sass 编译器输出的是可读的、非压缩的 CSS，这样 CssMinimizerPlugin 才能在后续步骤中选择性地对其进行压缩。
-
优化 (Optimization) 配置：
- minimize: true: 启用 Webpack 的默认最小化功能。
- minimizer 数组：
- TerserPlugin: 专门用于 JavaScript 文件的压缩。通过 include: /\.min\.js$/，我们指示 Webpack 只对那些文件名以 .min.js 结尾的 JavaScript 文件执行压缩。
- CssMinimizerPlugin: 专门用于 CSS 文件的压缩。同样，include: /\.min\.css$/ 确保只有文件名以 .min.css 结尾的 CSS 文件才会被压缩。这种选择性压缩是实现同时生成压缩与非压缩版本的核心。
-
插件 (Plugins) 配置：
4. 注意事项与优化
4.1 Source Map 配置
为了便于调试，建议启用 Source Map。您可以在 module.exports 对象中添加 devtool: 'source-map'。这将为您的构建输出生成对应的 .map 文件。
module.exports = {
devtool: 'source-map', // 启用 Source Map
// ... 其他配置
};4.2 残留文件的处理
由于 Webpack 的设计机制，即使 MiniCssExtractPlugin 成功提取了 CSS 文件，Webpack 仍然会为那些最初被视为 JavaScript 入口点的 CSS 源文件（例如 css/template 和 css/template.min）生成空的或包含少量引导代码的 .js 文件（例如 dist/media/templates/site/tofu/css/template.js 和 dist/media/templates/site/tofu/css/template.min.js）。这些文件通常是无用的“存根”。
为了保持输出目录的整洁，您可以在构建完成后手动删除这些残留的 .js 文件。这通常通过在 package.json 的构建脚本中添加 rm 命令来实现：
{
"name": "your-project",
"version": "1.0.0",
"scripts": {
"build": "webpack --mode production && rm -rf dist/media/templates/site/tofu/css/*.js"
},
"devDependencies": {
// ...
}
}执行 npm run build 命令时，Webpack 将首先构建项目，然后 rm -rf dist/media/templates/site/tofu/css/*.js 命令会删除 dist/media/templates/site/tofu/css/ 目录下所有多余的 .js 文件。
4.3 Joomla 特定路径
示例中的 media_root_path (media/templates/site/tofu) 是 Joomla 模板的典型路径结构。在实际项目中，请根据您的模板名称和结构调整此路径，确保资源被部署到正确的位置。
4.4 生产环境与开发环境区分
在更复杂的项目中，通常会为开发环境和生产环境使用不同的 Webpack 配置。例如，开发环境可能不需要最小化，但需要更快的构建速度和更详细的 Source Map。这可以通过以下方式实现：
- 使用 webpack-merge： 创建一个通用配置，然后为开发和生产环境分别创建特定配置并进行合并。
- 使用 mode 选项： Webpack 的 mode 选项（'development' 或 'production'）会自动启用一些默认优化。您可以在 package.json 脚本中指定："build": "webpack --mode production"。
5. 总结
通过本教程的配置，您已成功设置 Webpack 5，能够从相同的源代码同时生成 JavaScript 和 CSS 的压缩版与非压缩版。关键在于：
- 细致的入口点命名 来区分不同输出版本。
- MiniCssExtractPlugin 负责 CSS 文件的正确提取和命名。
- TerserPlugin 和 CssMinimizerPlugin 结合 include 选项 实现选择性压缩。
- 后处理脚本 用于清理构建过程中可能产生的无用文件。
这种配置方式不仅提高了开发效率，也为生产环境提供了优化的前端资源，是现代前端工程实践中的重要一环。
