5月27日 16:54

Rspack Dev Server 如何配置和使用？

Rspack Dev Server 为本地开发提供热更新、代理、HTTPS 等能力，是日常开发的核心工具。Rspack 2.0 对 Dev Server 做了较大重构：底层从 Express 切换到 connect-next，@rspack/cli 不再自动依赖 @rspack/dev-server，需要手动安装。本文基于 Rspack 2.0，系统讲解 Dev Server 的配置和使用。

安装与启动

Rspack 2.0 起，@rspack/dev-server 是可选依赖，需手动安装：

bash
npm add @rspack/dev-server -D

启动开发服务器有两种方式：

bash
# 方式一：rspack dev（推荐）
npx rspack dev

# 方式二：rspack serve（兼容写法）
npx rspack serve

指定配置文件或端口：

bash
npx rspack dev --config rspack.config.js --port 8080

在配置文件中声明 Dev Server 选项：

javascript
// rspack.config.js
module.exports = {
  mode: 'development',
  devServer: {
    static: {
      directory: path.join(__dirname, 'public'),
    },
    compress: true,
    port: 9000,
  },
};

核心功能

模块热更新（HMR）

HMR 默认在 development 模式下启用，修改代码后页面局部刷新而不需要整页重载：

javascript
module.exports = {
  devServer: {
    hot: true,   // 启用 HMR（默认开启）
    liveReload: false, // 禁用整页自动刷新
  },
};

注意：当 output.cssFilename 包含 [hash] 或 [contenthash] 时，CSS 的 HMR 不会生效。

静态文件服务

Dev Server 可以为静态资源提供文件服务：

javascript
module.exports = {
  devServer: {
    static: {
      directory: path.join(__dirname, 'public'),
      publicPath: '/',
      serveIndex: true,
      watch: true,
    },
  },
};

watch: true 会在静态文件变化时自动刷新页面，serveIndex: true 则允许浏览目录列表。

代理配置

开发环境常需解决跨域问题，Dev Server 内置了基于 http-proxy-middleware 的代理：

javascript
module.exports = {
  devServer: {
    proxy: {
      '/api': {
        target: 'http://localhost:3000',
        changeOrigin: true,
        pathRewrite: { '^/api': '' },
      },
    },
  },
};

也支持数组格式，适合更复杂的匹配场景：

javascript
module.exports = {
  devServer: {
    proxy: [
      {
        context: ['/api', '/graphql'],
        target: 'http://localhost:3000',
        changeOrigin: true,
      },
    ],
  },
};

HTTPS 支持

本地开发需要 HTTPS 时（如测试 Service Worker、Secure Cookie 等）：

javascript
const fs = require('fs');

module.exports = {
  devServer: {
    server: {
      type: 'https',
      options: {
        key: fs.readFileSync('path/to/private.key'),
        cert: fs.readFileSync('path/to/certificate.pem'),
      },
    },
  },
};

高级配置

错误覆盖与客户端日志

Dev Server 可以在浏览器中实时显示编译错误，辅助快速定位问题：

javascript
module.exports = {
  devServer: {
    client: {
      overlay: {
        errors: true,
        warnings: false,
      },
      logging: 'warn',
    },
  },
};

historyApiFallback

SPA 应用需要将所有路由回退到 index.html，避免刷新页面时 404：

javascript
module.exports = {
  devServer: {
    historyApiFallback: {
      index: '/index.html',
      rewrites: [
        { from: /^\/api/, to: '/404.html' },
      ],
    },
  },
};

文件监听

当需要监听源码之外的文件变化（如 PHP 模板、公共资源）时：

javascript
module.exports = {
  devServer: {
    watchFiles: {
      paths: ['src/**/*.php', 'public/**/*'],
      options: {
        usePolling: false,
        interval: 1000,
      },
    },
  },
};

devMiddleware 选项

控制构建输出的写入和日志行为：

javascript
module.exports = {
  devServer: {
    devMiddleware: {
      index: true,
      writeToDisk: false,
      stats: 'minimal',
    },
  },
};

writeToDisk: false 表示构建产物仅存在内存中，加快速度；stats 控制终端日志的详细程度，可选 none、errors-only、minimal、normal、verbose。

自定义中间件

Rspack 2.0 的 connect-next 适配

Rspack 2.0 将底层从 Express 替换为 connect-next，中间件写法需要适配：

javascript
module.exports = {
  devServer: {
    setupMiddlewares: (middlewares, devServer) => {
      if (!devServer) {
        throw new Error('devServer is not defined');
      }

      devServer.app.get('/health', (req, res) => {
        res.json({ status: 'ok' });
      });

      return middlewares;
    },
  },
};

如果项目仍依赖 Express 特有 API（如 req.query 的解析行为），可以显式提供 Express 实例：

javascript
import express from 'express';

export default {
  devServer: {
    app: async () => express(),
  },
};

WebSocket 配置

自定义 WebSocket 连接地址和服务端类型：

javascript
module.exports = {
  devServer: {
    client: {
      webSocketURL: 'auto://0.0.0.0:0/ws',
    },
    webSocketServer: {
      type: 'ws',
      options: {
        host: 'localhost',
        port: 8080,
      },
    },
  },
};

也支持使用自定义 WebSocket 客户端实现，继承 BaseClient 类即可。

压缩与性能

启用 gzip 压缩减少传输体积：

javascript
module.exports = {
  devServer: {
    compress: true,
  },
};

配合 devMiddleware 的 stats 选项保持终端输出简洁，能显著提升开发体验。

从 Rspack 1.x 迁移

Rspack 2.0 的 Dev Server 有几项破坏性变更需要注意：

必须手动安装 @rspack/dev-server：@rspack/cli 不再自动包含此依赖
底层切换为 connect-next：如果使用了 Express 专有 API，需显式提供 app: async () => express()
Node.js 版本要求：Rspack 2.0 要求 Node.js 20.19+ 或 22.12+，不再支持 Node 18
ESM-only 发布：@rspack/dev-server 已移除 CommonJS 构建，纯 ESM 包

最佳实践

开发/生产分离：Dev Server 仅用于开发环境，生产部署使用静态文件服务器
代理环境变量化：代理目标地址通过环境变量管理，避免硬编码
按需监听文件：watchFiles 只监听必要路径，避免不必要的重编译
合理配置日志：生产前关闭 overlay，日常开发使用 errors-only 或 minimal
HTTPS 按需开启：仅在需要安全上下文（Service Worker、Secure Cookie 等）时配置 HTTPS

标签：Rspack