webpack 为什么这么难用？

我从多年前的 webpack 1.0 时代就一直在用它，现在也不能说完全掌握了它，很多时候真的让我产生了怀疑，究竟是因为我的能力不足，还是因为 webpack 自身的设计就太难用？随着我接触到越来越多的前端项目，听到越来越多的吐槽，我也越发地相信，是 webpack 自身的问题，导致它变得如此复杂又难用。

举个简单的例子，一个 vue-cli 生成的最简单的脚手架项目，开发、构建相关的文件就有 14 个之多，代码超过 800 行，而真实的项目只会比这个更多：

所以，既然这篇文章的标题是《webpack 为什么这么难用？》，那我们就好好在这里分析一下，webpack 难用的根本原因。

一、文档极其不完善

是的，这就是第一位的原因。

真的想说 webpack 即使经过了这么多年的不断迭代，如今的文档依然还是是一坨那啥。作为一个开源项目，设计好不好、易用性怎么样、扩展性怎么样这些问题都是仁者见仁智者见智的，但文档写得很烂这一点上，真的没有任何可以开脱的理由。

对于使用者的不友好

比如，webpack 的插件体系可以说是 webpack 最核心的一部分功能了，基本上一个项目的构建中，大部分任务都是由各种插件完成的。然而，官方文档上对于插件的介绍只有寥寥几句话：webpack · Plugins，甚至推荐你直接去看 webpack 的源码：

更糟的是，现有的文档里（包括 webpack 一些插件的文档也是），大部分内容都是在告诉你 “你这样做就可以了”，而没有解释 “你为什么需要这么做” 以及 “你这么做了会有哪些后果”。

比如，在 target 配置上，官方文档里列举了你可以构建到哪些 target，如 node、node-webkit、electron-main，但都只是简单的一句话带过：

想知道 target 为 electron-main 时，和浏览器环境的打包有什么不同？对不起，官方文档不想告诉你，看源码或者去 stackoverflow 上搜吧。

官方文档语焉不详的直接后果就是，当你遇到了任何问题，你都没办法在文档里得到直接的回答，而是需要看无数的代码、github issue、stackoverflow、博客文章，然后在自己的项目里反反复复试了好多次，才能大致解决问题。而这种所谓的“解决问题”，一般都是个人经验性的，意味着其它任何一个人想要解决这个问题，都要重复一遍这个流程，时间成本大量上升。

对于开发者的不友好

我们要如何开发一个 webpack 的插件？

官方文档里确实写了一些关于如何开发插件的指南。但这份指南也只有 60 分刚及格的水平，它确实向你介绍了 webpack 插件的基础范例、基本概念以及一些 API，但当你读完这份简短的文档后想自己真的去开发一个插件时，你会发现文档里讲的东西真的远远不够。

我们不妨来看看现在 webpack 生态里那些成熟的插件是怎么写的，以 html-webpack-plugin 为例，这是一个广泛用于生成 html 文件的插件。在它的源码里你会发现，它引用了五个 webpack 内部自带的插件（源码在这里）：

var NodeTemplatePlugin = require('webpack/lib/node/NodeTemplatePlugin');
var NodeTargetPlugin = require('webpack/lib/node/NodeTargetPlugin');
var LoaderTargetPlugin = require('webpack/lib/LoaderTargetPlugin');
var LibraryTemplatePlugin = require('webpack/lib/LibraryTemplatePlugin');
var SingleEntryPlugin = require('webpack/lib/SingleEntryPlugin');

嗯哼？这五个插件都是用来干什么的？

官方文档上对内置的插件一个字都没有提及，是的，甚至连 Plugins 这里都没有。官方的 wiki 上倒是写了，但真的真的太简略了，而且看起来很久没更新了。

import RequestShortener from 'webpack/lib/RequestShortener';
import ModuleFilenameHelpers from 'webpack/lib/ModuleFilenameHelpers';

文档里同样没有对这两个文件做任何介绍。令人欣慰（？）的是，这两个文件从文件名上看，起码是方法库（实际上也确实是），使用起来不会太复杂。

换句话说，如果你想给 webpack 写一个广为人知的插件，你就必须深入了解 webpack 的全部，这一点我不反对，毕竟 webpack 开发者和 webpack 使用者在能力的要求上有高低之分。但即使是有经验的开发者，遇到一个文档如此不完善的开源项目，也是很吃力的。很多能帮助开发者的东西本应该正大光明地写在文档和指南里，而不是隐藏在源代码里。