webpack-serve是一个轻量、现代的 webpack 开发服务器。对于单页应用（SPA）来说，开发时最常踩的两个坑是：前端路由刷新返回 404，以及接口跨域无法调用。好消息是，你不需要在webpack-serve之外再搭一层代理——只需一份serve配置，就能同时完成 SPA 路由回退（history fallback）和 API 代理（proxy），让本地开发一步到位。

一、先认识 add 扩展选项

webpack-serve的核心理念是保持精简，把扩展能力交给使用者。它的serve配置中有一个add选项，接收一个函数，参数是 Koa 应用实例app、中间件访问器middleware和内部options。

在 lib/app.js 中可以看到，服务器启动时会在绑定端口前执行options.add，这就是你"往开发服务器里塞自定义中间件"的官方入口：

serve: { add: (app, middleware, options) => { // 这里添加路由回退、API 代理等中间件 } };

💡serve配置可以直接写在webpack.config.js的serve属性里，也可以放在.serverc、serve.config.js等文件中，详见 README.md。

二、SPA路由回退：一行接入 connect-history-api-fallback

当你用history模式的前端路由（如react-router的BrowserRouter）时，直接访问localhost:8080/user/42或刷新页面，服务器找不到这个路径就会返回 404。connect-history-api-fallback中间件的作用就是：把这类"本该 404 的请求"改写回index.html，交给前端路由自行处理。

官方示例见 docs/addons/history-fallback.config.js，核心只有两行：

app.use(convert(history()));

其中koa-connect（convert）负责把 connect 风格的中间件适配到 Koa。完整配方里还设置了content: [__dirname]来提供静态文件。

三、API代理：http-proxy-middleware 转发请求

前端调用/api/*接口时跨域，最简单的办法是让开发服务器把/api前缀的请求转发到真正的后端服务，http-proxy-middleware就能做到：

app.use(convert(proxy('/api', { target: 'http://localhost:8081' })));

这条规则会把所有localhost:8080/api/*的请求转发到localhost:8081/api/*；如果后端接口不带/api前缀，只需加上pathRewrite: { '^/api': '' }即可去掉前缀。

四、终极配方：一份 serve 配置同时搞定两者

把上面两部分合并，就是官方推荐的组合方案，完整示例在 docs/addons/proxy-history-fallback.config.js：

module.exports.serve = { content: [__dirname], add: (app, middleware, options) => { // ① 先代理 /api 请求到后端 app.use(convert(proxy('/api', { target: 'http://localhost:8081' }))); // ② 再兜底做路由回退 app.use(convert(history())); } };

顺序很关键：代理规则必须放在路由回退之前。这样/api开头的请求先被拦截转发，其余非静态文件请求才落进 fallback 返回index.html，两者互不干扰。

运行方式保持简洁：

$ webpack-serve ./webpack.config.js

启动后访问http://localhost:8080，前端路由可随意跳转刷新，/api接口也直接走通，不再需要浏览器插件开跨域。

五、进阶玩法与常见坑

• 代理需要排在内置中间件之后？默认webpack-serve会在最后追加 webpack 与静态内容中间件。如果你的自定义路由（如koa-router）必须最后执行，可在add中主动调用middleware.webpack()和middleware.content()接管顺序，参考 docs/addons/proxy-router.config.js。
• 静态文件优先级：默认 webpack 产物优先于静态文件；想让静态文件优先，调用middleware.content()时注意顺序即可。
• --no-reload与--open：CLI 支持--open自动打开浏览器、--port指定端口（默认 8080），完整参数用webpack-serve --help查看。
• 更多扩展思路：docs/addons/ 目录还收录了 gzip 压缩（express-compress.config.js）、局域网 IP 绑定（local-ip.config.js）、监听静态内容变化（watch-content.config.js）等配方，可举一反三。

⚠️ 注意：webpack-serve官方已宣布弃用并推荐使用webpack-dev-server。但如果你维护的老项目正基于它，本文的add中间件组合模式依然清晰可用，且这套"proxy + history fallback"的思路迁移到webpack-dev-server的devServer配置中几乎一比一成立。

小结

掌握add选项后，webpack-serve的开发服务器就从"只能跑页面"升级成"页面 + 路由 + 接口"一站就绪。照着 docs/addons/proxy-history-fallback.config.js 抄一份，今天就能省掉跨域调试的时间。