devServer 代理 404、热更新不生效：Webpack 本地联调清单

本地 npm start 后接口全 404，或改 React 组件必须整页刷新——多半是 devServer 没按你想的方式启动，或 proxy/HMR 配在「并没有被用到的配置文件」里。索引见 Webpack 问题索引。

你遇到的问题

现象	更可能是
接口 404，直打后端正常	proxy 路径/目标写错，或没走 devServer
CORS 报错	请求没被代理，浏览器直打了后端域名
改代码无 HMR	未开 hot，或自定义 server 未接中间件
CLI 直接跑 `webpack-dev-server` 失败	应走 `package.json` scripts 以解析本地 bin

解法清单

1. 用 scripts 启动

{
  "scripts": {
    "start": "webpack serve --mode development"
  }
}

不要依赖全局错位的 webpack-dev-server 命令。

2. proxy 最小例

devServer: {
  hot: true,
  historyApiFallback: true,
  proxy: {
    "/api": {
      target: "http://localhost:3001",
      changeOrigin: true,
    },
  },
},

前端请求保持同源 /api/...，由 devServer 转发。

3. HMR

hot: true（webpack-dev-server）
框架层按需接 React Fast Refresh 等插件
改 HTML 模板通常仍需整页刷新——属预期

4. 自定义 Node server

若用 middleware 自建，确保 webpack-dev-middleware + webpack-hot-middleware（或等价）都挂上，且浏览器连的是这个端口。

如何验证

Network 里 /api 请求 Host 为本地前端源，状态不再是前端 404
改组件后控制台有 HMR 成功日志，UI 局部更新
直连后端与经代理的响应体一致

下一步

慢编译见构建太慢。
网关侧超时见 Nginx 相关文。
更多历史笔记在索引长文「开发环境」章节。