Rsbuild 配备了一个内置的开发服务器,旨在提升开发体验。当你执行 rsbuild dev
或 rsbuild preview
命令时,该服务器将启动,并提供页面预览、路由、模块热更新等功能。
默认情况下,服务端的基础路径为 /
,用户可通过 http://localhost:3000/ 访问到 index.html
等产物资源、以及 public 目录下的资源。
Rsbuild 支持通过 server.base 修改服务端的基础路径。当我们希望通过 http://localhost:3000/foo/ 访问到这些资源时,可以添加如下配置:
Rsbuild 的 Server 提供一套默认的路由约定,并允许用户通过配置项定制。
Rsbuild Server 会根据 server.base 和 source.entry 配置生成对应的页面路由。
当 entry 为 index 时,可通过 /
访问页面;当 entry 为 foo 时,可通过 /foo
访问该页面。
当 server.base 为 /base
时,可通过 /base
访问 index 页面,通过 /base/foo
访问 foo 页面。
当请求满足以下条件且未找到对应资源时,会被 server.htmlFallback
处理,默认会回退到 index.html。
text/html
(请求头 accept 类型为 text/html
或 */*
)当 Rsbuild 默认的 server.htmlFallback 配置无法满足你的需求,例如,希望在访问 /
时可以访问 main.html
,可通过 server.historyApiFallback 进行设置。
通常情况下,/
指向 dist 产物根目录, 而 HTML 文件输出到 dist 根目录下,此时可通过 /some-path
访问对应的 HTML 页面。
若通过修改 output.distPath.html 将 HTML 文件输出到其他子目录下,此时需通过 /[htmlPath]/some-path
访问对应的 HTML 页面。
例如,设置将 HTML 文件输出到 HTML
目录下,此时将通过 /html/
访问到 index.html,通过 /html/foo
访问到 foo.html。
Rspack CLI 内置的开发服务器是 @rspack/dev-server,Rsbuild 没有使用 @rspack/dev-server
,而是自行实现了一个更轻量的版本。
Rsbuild 的开发服务器和 @rspack/dev-server
有以下区别:
@rspack/dev-server
基于 express 实现,三方依赖较多。Rsbuild 则采用 connect
等更轻量的库实现。Rsbuild 不支持使用 Rspack 的 devServer 配置项,你可以使用 Rsbuild 的 dev
和 server
配置代替。
在 Rsbuild 里,dev
包含一些仅在开发阶段生效的配置,而 server
配置对开发服务器和 preview 服务器均能生效。
以下是 Rspack CLI 的 devServer
配置对应的 Rsbuild 配置:
更多配置请参考 Config 总览。
Rsbuild server 未使用任何 Node.js 框架,Rsbuild 中间件提供的 req 和 res 均为 Node.js 原生对象。
这意味着,当你从其他服务端框架迁移时(如 Express),原本的中间件不一定能直接在 Rsbuild 中使用,例如,无法在 Rsbuild 中间件中访问 Express 所提供的 req.params
、req.path
、req.search
、req.query
等属性。
如果你需要在 Rsbuild 中使用原有的中间件,可以采取以下方式,将服务端应用作为中间件传入:
如果你希望将 Rsbuild dev server 集成到自定义的 server 中,可以通过 Rsbuild createDevServer
方法获取 Rsbuild dev server 的实例方法,进行按需调用。
详情可参考 Rsbuild - createDevServer。