Webpack CLI 脚手架的自定义扩展
2021-09-247.3k 阅读
理解 Webpack CLI 脚手架
Webpack 是现代前端开发中不可或缺的工具，它能够将各种类型的资源（如 JavaScript、CSS、图片等）进行打包、优化和转换，以适应不同环境的部署需求。Webpack CLI 则是与 Webpack 交互的命令行界面，通过它我们可以方便地执行各种 Webpack 相关的操作，比如启动开发服务器、进行生产环境构建等。
Webpack CLI 脚手架为开发者提供了一种快捷的项目初始化方式。以常见的 webpack -cli init 命令为例，它可以根据预设的模板快速搭建一个包含基本 Webpack 配置的项目结构。例如，当我们运行这个命令时，会看到如下交互界面：
? Please choose which app template to generate: (Use arrow keys)
❯ webpack-hello-world - A simple "Hello, world" example
webpack-advanced - An example that shows advanced webpack features
webpack-browser - An example that uses webpack to build a browser app
webpack-node - An example that uses webpack to build a Node.js app
选择其中一个模板后，脚手架会在指定目录生成相应的项目结构，包含基础的 webpack.config.js 文件、package.json 以及一些必要的源文件。例如，选择 webpack-hello-world 模板后，生成的项目结构可能如下：
my-project/
├── package.json
├── src/
│ └── index.js
└── webpack.config.js
这里的 webpack.config.js 包含了基本的 Webpack 配置，如入口文件、输出路径等。
自定义扩展的必要性
虽然 Webpack CLI 提供的默认脚手架模板能够满足一些基本项目需求，但在实际开发中，不同项目往往有特定的结构、配置和依赖要求。例如，一个使用 React 和 Redux 的项目，可能需要特定的 Babel 配置来支持 JSX 和 ES6+ 语法，还需要安装 React、Redux 及其相关的依赖。如果每次都手动修改默认模板生成的项目结构和配置，不仅繁琐，还容易出错。
通过自定义扩展 Webpack CLI 脚手架，我们可以创建符合项目特定需求的模板。比如，我们可以将常用的 React + Redux + Sass + ESLint 配置集成到一个自定义模板中。这样，当我们开始一个新的此类项目时，只需使用自定义的脚手架命令，就能快速搭建一个完整且符合项目规范的开发环境，大大提高开发效率。
自定义扩展的实现原理
Webpack CLI 脚手架的自定义扩展基于插件机制。Webpack CLI 插件本质上是一个 JavaScript 模块，它通过注册特定的钩子函数来扩展脚手架的功能。这些钩子函数在脚手架执行的不同阶段被调用，比如初始化项目时、安装依赖时等。
当我们创建一个自定义插件时，需要导出一个包含钩子函数的对象。例如，hooks.init 钩子会在脚手架初始化项目时被调用，我们可以在这个钩子函数中执行创建项目目录结构、写入配置文件等操作。
创建自定义扩展插件
- 初始化插件项目 首先，我们创建一个新的 Node.js 项目作为我们的自定义插件。在终端中执行以下命令：
mkdir my-webpack-cli-plugin
cd my-webpack-cli-plugin
npm init -y
这将创建一个新的目录，并初始化一个 package.json 文件。
- 安装依赖
我们需要安装
@webpack-cli/init - template - api，这个库提供了与 Webpack CLI 脚手架交互的 API。执行以下命令安装：
npm install @webpack-cli/init - template - api
- 编写插件代码
在项目根目录下创建一个
index.js文件，这将是我们插件的入口文件。以下是一个简单的示例，展示如何在项目初始化时创建一个自定义目录结构：
const { hooks } = require('@webpack-cli/init - template - api');
hooks.init.tap('MyPlugin', (answers, path) => {
const fs = require('fs');
const pathModule = require('path');
// 创建 src 目录
const srcPath = pathModule.join(path,'src');
if (!fs.existsSync(srcPath)) {
fs.mkdirSync(srcPath);
}
// 在 src 目录下创建 main.js 文件
const mainFilePath = pathModule.join(srcPath,'main.js');
fs.writeFileSync(mainFilePath, `console.log('Hello from custom plugin!');`);
});
module.exports = {};
在上述代码中，我们使用 hooks.init 钩子，当脚手架初始化项目时，它会在项目目录下创建一个 src 目录，并在 src 目录中创建一个 main.js 文件，写入一段简单的日志语句。
- 发布插件
如果希望在不同项目中方便地使用这个插件，我们可以将其发布到 npm 上。首先，确保在
package.json中正确填写了插件的名称、版本、描述等信息。然后执行以下命令登录 npm 并发布：
npm login
npm publish
使用自定义扩展插件
- 本地使用
如果我们还没有将插件发布到 npm，也可以在本地项目中使用。假设我们有一个要初始化的项目目录
my - new - project，在该目录下执行以下命令：
npx webpack - cli init /path/to/my - webpack - cli - plugin
这里 /path/to/my - webpack - cli - plugin 是我们自定义插件项目的路径。执行上述命令后，就会按照插件定义的逻辑初始化项目。
- 全局使用（发布后） 当我们将插件发布到 npm 后，可以全局安装并使用。首先全局安装插件：
npm install -g my - webpack - cli - plugin
然后在任意项目目录下执行：
npx webpack - cli init my - webpack - cli - plugin
这样就可以使用自定义插件来初始化项目了。
自定义扩展中的复杂功能实现
- 配置文件生成
在实际项目中，我们通常需要生成复杂的配置文件，如
webpack.config.js、.babelrc等。以生成webpack.config.js为例，我们可以在插件中根据用户的选择生成不同的配置。假设我们希望插件支持生成支持 React 的 Webpack 配置，代码如下：
const { hooks } = require('@webpack-cli/init - template - api');
const path = require('path');
hooks.init.tap('MyReactPlugin', (answers, projectPath) => {
const fs = require('fs');
const webpackConfig = {
entry: path.join(projectPath,'src', 'index.js'),
output: {
path: path.join(projectPath, 'dist'),
filename: 'bundle.js'
},
module: {
rules: [
{
test: /\.jsx?$/,
exclude: /node_modules/,
use: {
loader: 'babel-loader',
options: {
presets: ['@babel/preset - env', '@babel/preset - react']
}
}
}
]
},
resolve: {
extensions: ['.js', '.jsx']
}
};
const configFilePath = path.join(projectPath, 'webpack.config.js');
fs.writeFileSync(configFilePath, `module.exports = ${JSON.stringify(webpackConfig, null, 2)}`);
});
module.exports = {};
上述代码生成了一个基本的支持 React 的 Webpack 配置文件，包含了入口、出口、Babel 加载器配置以及文件扩展名解析配置。
- 依赖安装 自定义插件还可以在项目初始化时自动安装必要的依赖。例如，对于上述支持 React 的项目，我们需要安装 React、React DOM 和 Babel 相关的依赖。可以在插件中添加如下代码：
const { hooks } = require('@webpack-cli/init - template - api');
const path = require('path');
const { execSync } = require('child_process');
hooks.init.tap('MyReactPlugin', (answers, projectPath) => {
// 生成 webpack.config.js 配置文件代码...
// 安装依赖
const dependencies = ['react','react - dom', '@babel/core', '@babel/preset - env', '@babel/preset - react', 'babel - loader'];
const installCommand = `npm install --save - dev ${dependencies.join(' ')}`;
try {
execSync(installCommand, { cwd: projectPath, stdio: 'inherit' });
} catch (error) {
console.error('Error installing dependencies:', error.message);
}
});
module.exports = {};
这里使用 child_process 模块的 execSync 方法在项目目录下执行 npm install 命令来安装所需的依赖。stdio: 'inherit' 选项确保安装过程中的日志能够正常输出到终端。
自定义扩展的交互功能
- 询问用户信息
我们可以通过插件与用户进行交互，获取项目特定的信息。例如，我们希望用户输入项目的名称，并在生成的文件中使用这个名称。可以使用
@webpack - cli/init - template - api提供的prompt函数来实现。修改插件代码如下：
const { hooks, prompt } = require('@webpack-cli/init - template - api');
const path = require('path');
const { execSync } = require('child_process');
hooks.init.tap('MyInteractivePlugin', async (answers, projectPath) => {
const questions = [
{
type: 'input',
name: 'projectName',
message: 'What is the name of your project?'
}
];
const response = await prompt(questions);
const fs = require('fs');
const readmeFilePath = path.join(projectPath, 'README.md');
fs.writeFileSync(readmeFilePath, `# ${response.projectName}`);
// 其他配置文件生成和依赖安装代码...
});
module.exports = {};
在上述代码中，prompt 函数返回一个 Promise，当用户回答问题后，我们获取到用户输入的项目名称，并将其写入到 README.md 文件中。
- 选择不同的配置选项 除了输入信息，还可以让用户选择不同的配置选项。比如，我们希望用户选择项目使用的 CSS 预处理器（Sass、Less 或 Stylus）。代码如下：
const { hooks, prompt } = require('@webpack-cli/init - template - api');
const path = require('path');
const { execSync } = require('child_process');
hooks.init.tap('MyCSSPlugin', async (answers, projectPath) => {
const questions = [
{
type: 'list',
name: 'cssPreprocessor',
message: 'Which CSS preprocessor do you want to use?',
choices: ['Sass', 'Less', 'Stylus']
}
];
const response = await prompt(questions);
let cssLoader = '';
let installDeps = [];
if (response.cssPreprocessor === 'Sass') {
cssLoader ='sass - loader';
installDeps = ['sass - loader','sass'];
} else if (response.cssPreprocessor === 'Less') {
cssLoader = 'less - loader';
installDeps = ['less - loader', 'less'];
} else if (response.cssPreprocessor === 'Stylus') {
cssLoader ='stylus - loader';
installDeps = ['stylus - loader','stylus'];
}
// 在 webpack.config.js 中添加相应的 CSS 预处理器配置代码...
// 安装依赖
const installCommand = `npm install --save - dev ${installDeps.join(' ')}`;
try {
execSync(installCommand, { cwd: projectPath, stdio: 'inherit' });
} catch (error) {
console.error('Error installing dependencies:', error.message);
}
});
module.exports = {};
这里通过 type: 'list' 类型的问题让用户选择 CSS 预处理器，然后根据用户的选择确定需要安装的依赖，并在后续代码中可以添加相应的 Webpack 配置来支持所选的预处理器。
自定义扩展与现有模板的结合
- 基于现有模板扩展
我们可以在 Webpack CLI 提供的现有模板基础上进行扩展。例如，我们基于
webpack - browser模板，添加一些自定义的配置和依赖。首先，我们需要了解webpack - browser模板的基本结构和配置。假设我们要在这个模板基础上添加 ESLint 支持。
我们可以先创建一个自定义插件，在插件中复用 webpack - browser 模板的初始化逻辑，然后添加 ESLint 相关的配置和依赖安装。代码如下：
const { hooks, prompt } = require('@webpack-cli/init - template - api');
const path = require('path');
const { execSync } = require('child_process');
hooks.init.tap('MyESLintPlugin', async (answers, projectPath) => {
// 复用 webpack - browser 模板的初始化逻辑
const originalInitHook = require('@webpack - cli/init - templates/webpack - browser').hooks.init;
await originalInitHook.call(this, answers, projectPath);
// 添加 ESLint 配置
const fs = require('fs');
const eslintConfig = {
env: {
browser: true,
es6: true
},
extends: 'eslint:recommended',
parserOptions: {
ecmaVersion: 2018,
sourceType:'module'
},
rules: {
semi: ['error','always']
}
};
const eslintConfigFilePath = path.join(projectPath, '.eslintrc.json');
fs.writeFileSync(eslintConfigFilePath, JSON.stringify(eslintConfig, null, 2));
// 安装 ESLint 依赖
const installCommand = `npm install --save - dev eslint`;
try {
execSync(installCommand, { cwd: projectPath, stdio: 'inherit' });
} catch (error) {
console.error('Error installing ESLint:', error.message);
}
});
module.exports = {};
在上述代码中，我们首先通过 require 引入 webpack - browser 模板的 init 钩子函数，并调用它来完成基本的项目初始化。然后添加 ESLint 配置文件并安装 ESLint 依赖。
- 混合多个模板特性
我们还可以混合多个现有模板的特性。比如，我们希望一个项目既有
webpack - browser模板的浏览器相关配置，又有webpack - node模板的 Node.js 相关配置。虽然这在实际中可能不常见，但展示了一种灵活的扩展方式。
const { hooks, prompt } = require('@webpack-cli/init - template - api');
const path = require('path');
const { execSync } = require('child_process');
hooks.init.tap('MyMixedPlugin', async (answers, projectPath) => {
// 复用 webpack - browser 模板的初始化逻辑
const browserInitHook = require('@webpack - cli/init - templates/webpack - browser').hooks.init;
await browserInitHook.call(this, answers, projectPath);
// 复用 webpack - node 模板的部分逻辑，比如添加 Node.js 特定的配置
const nodeInitHook = require('@webpack - cli/init - templates/webpack - node').hooks.init;
await nodeInitHook.call(this, answers, projectPath);
// 处理可能的冲突或合并配置（这里只是示例，实际可能需要更复杂的逻辑）
const webpackConfigPath = path.join(projectPath, 'webpack.config.js');
let webpackConfig = require(webpackConfigPath);
webpackConfig.target = 'node'; // 假设将目标设置为 Node.js
fs.writeFileSync(webpackConfigPath, `module.exports = ${JSON.stringify(webpackConfig, null, 2)}`);
});
module.exports = {};
上述代码通过先后调用 webpack - browser 和 webpack - node 模板的 init 钩子函数来初始化项目，并对生成的 webpack.config.js 文件进行简单的修改，将目标设置为 Node.js，以混合两个模板的特性。
自定义扩展的测试与调试
- 单元测试
对于自定义插件中的逻辑，我们可以编写单元测试来确保其正确性。可以使用
jest等测试框架。假设我们有一个函数用于生成特定的配置文件内容，代码如下：
function generateWebpackConfig() {
return {
entry: './src/index.js',
output: {
path: './dist',
filename: 'bundle.js'
}
};
}
module.exports = {
generateWebpackConfig
};
我们可以编写如下的 jest 测试：
const { generateWebpackConfig } = require('./index');
test('should generate correct webpack config', () => {
const config = generateWebpackConfig();
expect(config.entry).toBe('./src/index.js');
expect(config.output.path).toBe('./dist');
expect(config.output.filename).toBe('bundle.js');
});
在项目根目录下执行 npm install --save - dev jest 安装 jest，然后在 package.json 中添加测试脚本：
{
"scripts": {
"test": "jest"
}
}
执行 npm test 即可运行测试。
- 集成测试
除了单元测试，我们还可以进行集成测试，以确保插件在实际使用场景中的正确性。可以创建一个临时项目目录，使用自定义插件初始化项目，然后检查生成的项目结构、配置文件和依赖是否正确。例如，使用
tmp库来创建临时目录，代码如下：
const { execSync } = require('child_process');
const tmp = require('tmp');
const path = require('path');
describe('MyPlugin integration test', () => {
let tmpDir;
beforeEach(() => {
tmpDir = tmp.dirSync().name;
});
afterEach(() => {
// 清理临时目录
require('fs - extra').removeSync(tmpDir);
});
it('should initialize project correctly', () => {
const pluginPath = path.join(__dirname, '..');
const initCommand = `npx webpack - cli init ${pluginPath}`;
try {
execSync(initCommand, { cwd: tmpDir, stdio: 'inherit' });
// 检查生成的文件和目录
const fs = require('fs');
const srcDir = path.join(tmpDir,'src');
const mainFile = path.join(srcDir,'main.js');
expect(fs.existsSync(srcDir)).toBe(true);
expect(fs.existsSync(mainFile)).toBe(true);
} catch (error) {
console.error('Error initializing project:', error.message);
}
});
});
在上述代码中，beforeEach 钩子函数在每个测试用例执行前创建一个临时目录，afterEach 钩子函数在测试用例执行后删除临时目录。测试用例中使用 npx webpack - cli init 命令在临时目录中使用自定义插件初始化项目，并检查生成的项目结构是否正确。
- 调试插件
在开发插件过程中，调试是必不可少的。我们可以在插件代码中添加
console.log语句来输出调试信息。例如：
const { hooks } = require('@webpack-cli/init - template - api');
hooks.init.tap('MyPlugin', (answers, path) => {
console.log('Initializing project with answers:', answers);
console.log('Project path:', path);
// 其他插件逻辑...
});
module.exports = {};
另外，如果使用的是 Node.js 的调试功能，可以在启动 webpack - cli init 命令时添加 --inspect 标志，然后使用调试工具（如 Chrome DevTools）连接到调试会话。例如：
node --inspect $(which webpack - cli) init /path/to/my - webpack - cli - plugin
这样就可以在调试工具中设置断点，逐步调试插件代码。
自定义扩展的优化与性能考虑
- 优化配置文件生成
在生成配置文件时，尽量避免重复生成相同的内容。例如，如果我们有多个插件都要向
webpack.config.js文件中添加规则，可以先读取已有的配置文件内容，然后合并新的规则，而不是每次都覆盖整个文件。假设我们有两个插件，一个添加 Babel 规则，一个添加 CSS 规则，代码如下：
// 插件 1：添加 Babel 规则
const { hooks } = require('@webpack-cli/init - template - api');
const path = require('path');
hooks.init.tap('BabelPlugin', (answers, projectPath) => {
const fs = require('fs');
const webpackConfigPath = path.join(projectPath, 'webpack.config.js');
let webpackConfig = {};
if (fs.existsSync(webpackConfigPath)) {
webpackConfig = require(webpackConfigPath);
}
if (!webpackConfig.module) {
webpackConfig.module = { rules: [] };
}
webpackConfig.module.rules.push({
test: /\.jsx?$/,
exclude: /node_modules/,
use: {
loader: 'babel-loader',
options: {
presets: ['@babel/preset - env', '@babel/preset - react']
}
}
});
fs.writeFileSync(webpackConfigPath, `module.exports = ${JSON.stringify(webpackConfig, null, 2)}`);
});
module.exports = {};
// 插件 2：添加 CSS 规则
const { hooks } = require('@webpack-cli/init - template - api');
const path = require('path');
hooks.init.tap('CSSPlugin', (answers, projectPath) => {
const fs = require('fs');
const webpackConfigPath = path.join(projectPath, 'webpack.config.js');
let webpackConfig = {};
if (fs.existsSync(webpackConfigPath)) {
webpackConfig = require(webpackConfigPath);
}
if (!webpackConfig.module) {
webpackConfig.module = { rules: [] };
}
webpackConfig.module.rules.push({
test: /\.css$/,
use: ['style-loader', 'css-loader']
});
fs.writeFileSync(webpackConfigPath, `module.exports = ${JSON.stringify(webpackConfig, null, 2)}`);
});
module.exports = {};
这样，两个插件可以协同工作，而不会互相覆盖配置。
- 依赖安装优化
在安装依赖时，可以考虑使用更高效的包管理器，如
yarn或pnpm。它们在安装依赖时通常比npm更快，特别是在处理大型项目依赖时。例如，我们可以在插件中检测用户是否安装了yarn，如果安装了则使用yarn安装依赖：
const { hooks } = require('@webpack-cli/init - template - api');
const path = require('path');
const { execSync } = require('child_process');
hooks.init.tap('MyPlugin', (answers, projectPath) => {
const dependencies = ['react','react - dom'];
try {
execSync('yarn --version', { stdio: 'ignore' });
const installCommand = `yarn add ${dependencies.join(' ')}`;
execSync(installCommand, { cwd: projectPath, stdio: 'inherit' });
} catch (yarnError) {
const installCommand = `npm install ${dependencies.join(' ')}`;
try {
execSync(installCommand, { cwd: projectPath, stdio: 'inherit' });
} catch (npmError) {
console.error('Error installing dependencies:', npmError.message);
}
}
});
module.exports = {};
此外，还可以通过设置 package.json 中的 resolutions 字段来优化依赖的安装版本，避免不必要的版本冲突和重复安装。
- 性能监控与分析
在开发自定义插件过程中，我们可以使用工具来监控和分析插件对项目初始化性能的影响。例如，可以使用
benchmark库来比较不同实现方式的性能。假设我们有两种生成配置文件的方式，一种是直接写入，一种是先读取再合并，代码如下：
const Benchmark = require('benchmark');
const fs = require('fs');
const path = require('path');
const suite = new Benchmark.Suite;
// 直接写入配置文件
suite.add('Direct write', function () {
const config = {
entry: './src/index.js',
output: {
path: './dist',
filename: 'bundle.js'
}
};
const configFilePath = path.join(__dirname, 'webpack.config.js');
fs.writeFileSync(configFilePath, `module.exports = ${JSON.stringify(config, null, 2)}`);
})
// 先读取再合并配置文件
.add('Read and merge', function () {
const configFilePath = path.join(__dirname, 'webpack.config.js');
let existingConfig = {};
if (fs.existsSync(configFilePath)) {
existingConfig = require(configFilePath);
}
const newConfig = {
entry: './src/index.js',
output: {
path: './dist',
filename: 'bundle.js'
}
};
const mergedConfig = {
...existingConfig,
...newConfig
};
fs.writeFileSync(configFilePath, `module.exports = ${JSON.stringify(mergedConfig, null, 2)}`);
})
// 添加监听事件
.on('cycle', function (event) {
console.log(String(event.target));
})
.on('complete', function () {
console.log('Fastest is'+ this.filter('fastest').map('name'));
})
// 运行测试
.run({ 'async': true });
通过这种方式，我们可以直观地了解不同实现方式的性能差异，从而选择更优的方案。
通过以上详细的步骤和方法，我们可以深入理解并实现 Webpack CLI 脚手架的自定义扩展，满足各种复杂项目的需求，提高前端开发的效率和质量。无论是简单的项目结构调整，还是复杂的配置生成和依赖管理，自定义扩展都为我们提供了强大的灵活性和扩展性。