webpack-serve 高级玩法清单:Bonjour、压缩、Chrome 标签页复用等 8 个官方配方

原创2026-10-16 09:14:541,359 阅读

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),逻辑分三级:

  1. 找到已经打开该 URL 的标签页 → 直接 reload 并激活;
  2. 没找到 → 占用一个空白新标签页(chrome://newtab/);
  3. 都没有 → 才新建标签页。
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 开发服务器的体验上一个台阶 💪

登录后查看全文
webpack-serve