webpack-serve 高级玩法清单:Bonjour、压缩、Chrome 标签页复用等 8 个官方配方
webpack-serve 高级玩法清单:Bonjour、压缩、Chrome 标签页复用等 8 个官方配方
webpack-serve 是一款轻量、灵活、现代风格的 webpack 开发服务器(development server)。除了内置的热更新(HMR)、HTTPS、事件订阅等能力外,它的 docs/addons 目录里还藏着一份"官方配方集"——Bonjour 局域网广播、响应压缩、Chrome 标签页复用等 8 个高级配方,全部基于同一个 add 扩展点实现。本清单逐一拆解这 8 个官方配方,教你快速为自己的开发服务器加料 🚀
先搞懂 add 选项:webpack-serve 开发服务器扩展的万能入口
所有配方的核心都只有一个选项:add。它是 serve 配置下的一个函数,签名如下:
add: (app, middleware, options) => {
// app —— 底层 Koa 应用,可直接 app.use(...) 挂中间件
// middleware —— 内置中间件访问器:webpack() 与 content()
// options —— webpack-serve 的内部配置对象
}
在服务器启动流程中,webpack-serve 会优先调用你提供的 add 函数,之后才按默认顺序挂载 webpack 编译中间件和静态内容中间件(见 lib/app.js)。两个内置中间件都做了记忆化(lib/middleware/MiddlewareState.js),所以你在 add 里提前调用它们不会重复执行——这正是"调整中间件顺序"类配方的关键。
除了 add,serve.on 还能订阅事件总线(lib/bus.js),比如 listening 事件会在服务器开始监听时触发,配方 1、5、8 都用到了它。
配方一:Bonjour 广播——让局域网设备发现你的开发服务器
场景:手机、平板、同事的电脑访问你的开发服务,不用再手输 IP。
Bonjour(即 Apple 的零配置网络协议)可以把你的服务器"发布"到局域网中。官方配方 bonjour.config.js 的做法是:在 listening 事件里调用 bonjour 包发布服务,进程退出时自动撤销。
serve: {
content: [__dirname],
on: {
listen(server) {
const bonjour = require('bonjour')();
bonjour.publish({
name: `Some Bitchin' App`,
port: server.address().port,
type: 'http',
subtypes: ['webpack'],
});
},
},
};
提示:发布后,支持 Bonjour 的设备(如 macOS、iOS)可以直接"看到"你的开发服务器,无需知道具体地址。
配方二:响应压缩——一行代码给静态资源加上 gzip
场景:大型 bundle 或静态资源加载慢,通过 HTTP 压缩显著减少传输体积。
webpack-serve 底层是 Koa,官方提供了两种压缩写法,放在 docs/addons/compress 目录下:
写法 A:koa-compress(Koa 原生风格),见 koa-compress.config.js:
add: (app) => {
app.use(require('koa-compress')());
},
写法 B:compression + koa-connect(Express 生态习惯),见 express-compress.config.js:
const compress = require('compression');
const convert = require('koa-connect');
add: (app) => {
app.use(convert(compress())); // 把 Express 风格中间件桥接到 Koa
},
两个文件结构完全相同,只需用哪个生态的包就选哪份。koa-connect 的作用是把"connect 风格"中间件(如 compression、history、proxy)包装成 Koa 中间件,后文的配方还会反复用到它。
配方三:SPA 路由回退——history 模式刷新不再 404
场景:React/Vue 单页应用使用 history 路由,刷新 /page/2 直接 404,需要把所有"非资源请求"回退到 index.html。
官方配方 history-fallback.config.js 引入 connect-history-api-fallback:
add: (app, middleware, options) => {
const history = require('connect-history-api-fallback');
const convert = require('koa-connect');
app.use(convert(history({ /* 可加 index、rewrites 等选项 */ })));
},
进阶:代理 API + 路由回退二合一
proxy-history-fallback.config.js 在同一份配置里同时完成两件事:
add: (app, middleware, options) => {
app.use(convert(proxy('/api', { target: 'http://localhost:8081' })));
app.use(convert(history()));
},
效果:所有 http://localhost:8080/api/* 请求被代理到后端 http://localhost:8081/api/*,其余会 404 的请求全部回退到 index.html。如果后端不希望路径带 /api 前缀,给 proxy 加一个 pathRewrite: { '^/api': '' } 即可。
注意中间件顺序:proxy 必须在 history 之前,否则 API 请求也会被改写进
index.html。
配方四:proxy + router——把开发服务器变成本地反向代理
场景:前端页面和第三方 API 跨域,想让页面直接"同域"请求外部接口。
官方配方 proxy-router.config.js 用 koa-router 兜住所有 GET 请求并转发给目标 API:
const router = new Router();
router.get('*', convert(proxy({
target: 'http://api.github.com',
changeOrigin: true,
})));
// serve 配置中:
add: (app, middleware, options) => {
middleware.webpack().then(() => {
middleware.content({ index: 'index.htm' });
app.use(router.routes()); // router 必须最后挂载
});
},
这里展示了一个关键技巧:当你需要把中间件挂到栈尾时,要自己手动调用 middleware.webpack() 和 middleware.content(),webpack-serve 会自动识别,不再重复执行。
配方五:Chrome 标签页复用——每次启动都刷同一个标签页
场景(macOS):每次重启开发服务器都被弹出一堆新标签页,调试标签越开越多。
官方配方 reuse-chrome-tab/webpack.config.js 在 listening 事件中通过 osascript 执行一段 AppleScript(chrome.applescript),逻辑分三级:
- 找到已经打开该 URL 的标签页 → 直接
reload并激活; - 没找到 → 占用一个空白新标签页(
chrome://newtab/); - 都没有 → 才新建标签页。
on: {
listening: () => {
execSync(
`osascript chrome.applescript "${encodeURI(`http://localhost:${port}")}"`,
{ cwd: __dirname, stdio: 'ignore' }
);
},
},
这样服务器无论重启多少次,Chrome 里永远只有一个开发服务器标签页。
配方六:静态内容选项——自定义 index 文件名等 koa-static 行为
场景:你的入口文件不叫 index.html(比如 index.aspx),想给静态中间件传自定义选项。
官方配方 static-content-options.config.js 只需提前调用两个内置中间件:
add: (app, middleware, options) => {
middleware.webpack().then(() =>
middleware.content({
index: 'index.aspx', // 其余 koa-static 选项同样可传
})
);
},
由于 content() 被记忆化,webpack-serve 启动时不会再以默认参数挂载它,你的自定义选项生效。
配方七:绑定本地 IP——手机连 WiFi 就能打开项目
场景:默认绑定 localhost,手机或同网段其他设备无法访问。
官方配方 local-ip.config.js 用 internal-ip 包自动取本机内网 IPv4 并绑定:
const internalIp = require('internal-ip');
serve: {
content: [__dirname],
host: internalIp.v4.sync(),
},
不用手写 192.168.x.x,换网络环境也不用改配置。之后把 http://内网IP:8080 发给同网段设备即可访问。
配方八:watch content——静态文件改动自动刷新浏览器
场景:改的不是 JS 源码(webpack 不会重新编译),比如 HTML、JSON、图片等静态内容,希望改动后浏览器自动刷新。
官方配方 watch-content.config.js 组合了三样东西:chokidar 监听目录、ws 连接热更新 WebSocket、向客户端广播 window-reload 消息。
serve: {
content: [__dirname],
hot: { host: 'localhost', port: 8090 },
on: {
listening(server) {
const socket = new WebSocket('ws://localhost:8090');
const watcher = chokidar.watch(__dirname, {});
watcher.on('change', () => {
socket.send(stringify({
type: 'broadcast',
data: { type: 'window-reload', data: {} },
}));
});
server.on('close', () => watcher.close());
},
},
},
原理:webpack-hot-client 会在浏览器里监听这个热更新端口,收到 window-reload 广播就整页刷新——等于用官方热更新通道给静态文件"蹭"了自动刷新能力。
8 个官方配方速查表
| # | 配方 | 解决的痛点 | 配方文件 | 关键依赖 |
|---|---|---|---|---|
| 1 | Bonjour 广播 | 设备互相发现,免记 IP | bonjour.config.js | bonjour |
| 2 | 响应压缩 | 传输体积大、加载慢 | compress/ | koa-compress / compression |
| 3 | 路由回退(含代理) | SPA history 模式刷新 404 | history-fallback.config.js、proxy-history-fallback.config.js | connect-history-api-fallback、http-proxy-middleware |
| 4 | 代理 + 路由 | 跨域调外部 API | proxy-router.config.js | koa-router、http-proxy-middleware |
| 5 | Chrome 标签页复用 | 标签页无限膨胀(macOS) | reuse-chrome-tab/ | osascript |
| 6 | 静态内容选项 | index 文件名非标准 | static-content-options.config.js | 无 |
| 7 | 绑定本地 IP | 手机/局域网访问 | local-ip.config.js | internal-ip |
| 8 | 监听静态内容 | 非 JS 文件改动不刷新 | watch-content.config.js | chokidar、ws |
上手建议与常见问题
- 配置放哪? 把配方代码并入
webpack.config.js的serve属性即可,也可以写在serve.config.js、.serverc或package.json的serve字段中,多来源配置会自动合并(可参考 test/fixtures/serve.config.js 这类示例文件)。 - 中间件顺序不对? 想改顺序时务必手动调用
middleware.webpack()/middleware.content(),否则 webpack-serve 会在栈尾按默认顺序再挂一次。 - 依赖装了吗? 每个配方用到的第三方包(如
bonjour、koa-compress、chokidar)需自行安装到 devDependencies。 - 想深入原理? 服务启动与
add调用在 lib/app.js,事件订阅在 lib/bus.js,完整选项清单见 README.md 与 schemas/options.json。
这 8 个配方覆盖了开发服务器最常见的"加料"需求:网络发现、性能优化、路由与代理、浏览器自动化。挑一份最贴近你痛点的配方复制到项目里,五分钟就能让 webpack-serve 开发服务器的体验上一个台阶 💪