webpack-serve是一款轻量、现代、灵活的webpack 开发服务器（development server）。相比 webpack-dev-server，它的核心思路是"保持精简"：内置热更新（HMR）、静态资源服务、HTTPS 等基础能力，其余功能（代理、History 回退、压缩等）通过add选项用几行熟悉的 Koa 中间件模式即可扩展。本文将带你5 分钟完成安装、启动与常用配置，快速跑起你的开发环境。

⚠️版本提示：该项目已标记为 DEPRECATED（见 README.md），官方建议使用仍在积极维护的 webpack-dev-server。本文仍完整介绍其用法，适合学习其设计理念、维护已有项目，或了解其扩展机制。

一、为什么值得了解 webpack-serve？

它的"被低估"之处在于：很多开发者只把开发服务器当作"启动命令"，而 webpack-serve 的add 扩展机制 + 事件总线设计，让代理、路由、History 回退等能力都以极简方式接入，代码可读性和可维护性都很高（核心实现见 lib/app.js 与 lib/middleware/WebpackMiddleware.js）。

二、一键安装：环境与依赖准备

1. 环境要求

• Node.js≥ v6.9.0
• Webpackv4.0.0（作为 peer 依赖，见 package.json）

2. 安装命令

$ npm install webpack-serve --save-dev

如果希望先拉取源码阅读，仓库地址为：

$ git clone https://gitcode.com/gh_mirrors/we/webpack-serve

安装完成后，CLI 入口指向 lib/cli.js，所有可用命令行参数定义在 schemas/flags.js 中，可以随时查阅。

三、30秒启动你的开发服务器

1. 最简启动（零配置）

在 webpack v4+ 项目中，直接运行即可，它会应用 webpack 的零配置默认值：

$ webpack-serve

2. 指定配置文件启动

$ webpack-serve ./webpack.config.js $ webpack-serve --config ./webpack.config.js --port 1337

两种写法完全等价。默认监听8080端口，启动后服务器 URI 会自动复制到剪贴板（可用--clipboard关闭）。

3. 常用命令行参数速查

💡 小贴士：所有布尔参数都支持no-前缀写法，例如--no-reload等价于--reload=false。

四、配置文件速成：4种方式任选其一

webpack-serve 基于 cosmiconfig 查找配置，支持以下 4 种方式（可叠加合并）：

1. webpack.config.js 中的serve属性（最常见，推荐）
2. serve.config.js文件（CommonJS 模块）
3. .serverc/.serverc.json文件（JSON 或 YML）
4. package.json中的serve字段

最推荐的写法：serve属性

在 webpack.config.js 中加一个serve字段即可：

const path = require('path'); module.exports = { context: __dirname, devtool: 'source-map', entry: ['./app.js'], output: { filename: './output.js', path: path.resolve(__dirname), }, serve: { port: 1337, content: ['./public'], // 静态资源目录 }, };

📌 小技巧：在配置中动态区分开发/生产模式——

mode: process.env.WEBPACK_SERVE ? 'development' : 'production',

因为 webpack-serve 启动时会自动设置WEBPACK_SERVE = true环境变量（见 lib/index.js 第 22 行）。

一个独立的serve.config.js实例可参考 test/fixtures/serve.config.js。

五、进阶玩法：add 选项 + 3个高频扩展配方

webpack-serve 的核心哲学是"保持精简 + 让用户用熟悉的模式扩展"。add选项接收一个函数，参数为(app, middleware, options)：

• app：底层 Koa 应用实例
• middleware：提供webpack()与content()两个访问函数
• options：内部选项对象

官方在 docs/addons/ 目录下提供了大量可直接抄的配方：

以 History 回退为例（摘自 docs/addons/history-fallback.config.js）：

module.exports.serve = { content: [__dirname], add: (app, middleware, options) => { app.use(convert(history(historyOptions))); }, };

⚠️ 注意：如果你调整了中间件顺序（例如路由必须最后注册），需要在add中手动调用middleware.webpack()与middleware.content()，webpack-serve 会识别这些调用并避免重复执行。

六、API 用法与事件监听

编程式启动

主入口是默认导出的serve函数（lib/index.js）：

const serve = require('webpack-serve'); serve({}, { config: require('./webpack.config.js') }) .then((result) => { // result.app —— Koa 实例（含 server 属性与 stop 方法） // result.on —— 绑定事件 // result.options —— 冻结后的内部选项 });

可订阅的事件

事件总线实现在 lib/bus.js，你可以在配置的on选项中直接订阅，例如在build-started时打印自定义日志。

七、HTTPS 与常见注意事项

• HTTPS：通过--https-cert、--https-key（或--https-pfx+--https-pass）命令行参数，或options.https对象开启安全服务。与 webpack-dev-server 不同，它不内置证书生成，官方建议自行生成受信任的本地证书。
• host 一致性：host必须与热更新客户端的 host 保持一致，否则 webpack-serve 会直接抛出错误——这是为了保证 Koa 服务器与 WebSocket 服务器协同正常。
• 静态资源优先级：默认 webpack 产物优先于content静态文件；想反过来，在add中先调middleware.content()再调middleware.webpack()即可。

八、总结：5分钟回顾

1. ✅装：npm install webpack-serve --save-dev（需 webpack v4）
2. ✅跑：webpack-serve或webpack-serve ./webpack.config.js
3. ✅配：在 webpack 配置里加serve字段，或写serve.config.js
4. ✅扩：add选项 + docs/addons/ 配方，自由组装代理、History、压缩
5. ✅控：serve()API + 事件订阅，实现编程化启动与构建反馈

webpack-serve 虽然已停止迭代，但它"核心极简、扩展靠社区模式"的设计思路，依然是理解 webpack 生态开发服务器的优质范本。如果你正在维护使用它的项目，或想对比它与 webpack-dev-server 的能力边界，本文的 README.md 与源码文件路径索引会是很好的导航起点。