React Router Server Bundles 完全指南利用 serverBundles 将路由树拆分为多个服务端请求处理入口【免费下载链接】react-routerDeclarative routing for React项目地址: https://gitcode.com/GitHub_Trending/re/react-routerServer Bundles服务端 Bundle 拆分是 React Router 为**托管方集成hosting provider integrations**设计的进阶特性属于 [MODES: framework] 场景。本文以官方文档 docs/how-to/server-bundles.md 为主体结合仓库源码与集成测试系统讲解如何在 react-router.config.ts 中通过serverBundles函数把整棵路由树按需分派到不同的服务端 bundle每个 bundle 各自导出独立的路由子集请求处理器并在buildEnd钩子中借助 Build Manifest 驱动自定义路由分发层。读完本文你将能设计认证区独立部署 / 大型站点按分区拆分的服务端产物结构并理解其底层约束可寻址路由、bundle ID 命名规则、SPA 与 RSC 限制等。1. 特性背景默认单 bundle 与多 bundle 的取舍在默认情况下React Routerreact-router/dev的 Vite 插件会把整个应用的服务端代码编译为单个 server bundle该 bundle 导出一个覆盖全部路由的请求处理器request handler函数产物通常位于build/server/index.js默认值见 config/config.tsbuildDirectory: build、serverBuildFile: index.js。然而在某些托管/部署场景下你会希望将应用的路由树拆成多个服务端 bundle每个 bundle 只为其中的一部分路由提供服务端请求处理由部署平台上层的自定义路由层edge gateway、CDN、负载均衡等根据 URL 把请求分发给正确的 bundle 入口。这好比把一整台应用服务器变成一组按 URL 分区负责的服务器组各分区可以独立扩缩容、独立回滚、独立冷启动。React Router 通过react-router.config.ts中的serverBundles配置项提供这一灵活性。需要特别强调的是这是文档明确标注的高级特性一旦拆分为多 bundle你的应用前方就必须存在一个自定义路由层负责把请求导向正确的 bundleReact Router 本身不会替你完成这一分发。集成测试 integration/vite-server-bundles-test.ts 也印证了这一点——它逐个启动只承载某一个 bundle的服务进程来验证行为而不是依赖单个进程同时服务所有路由。2.serverBundles函数路由 → Bundle 的分派器serverBundles是 react-router.config.ts 顶层配置之一。其类型定义于 config/config.tsexport type ServerBundlesFunction (args: { branch: BranchRoute[]; }) string | Promisestring;它会被**路由树中的每条可寻址路由addressable route**调用返回一个字符串作为该路由所属的server bundle ID这些 bundle ID 会被用作服务端构建输出目录的名称例如返回authenticated则产物出现在build/server/authenticated/。2.1 官方示例按布局路由拆分认证区文档给出的典型用法是为某个布局下的所有路由单独创建 bundle。由于函数收到的是从根路由到当前路由的整条branch你可以通过检查祖先路由的id来判断归属import type { Config } from react-router/dev/config; export default { // ... serverBundles: ({ branch }) { const isAuthenticatedRoute branch.some((route) route.id.split(/).includes(_authenticated), ); return isAuthenticatedRoute ? authenticated : unauthenticated; }, } satisfies Config;该示例中凡是被_authenticated布局以点号分段标识嵌套关系其 routeid形如routes/_authenticated包裹的子路由其 branch 里必然包含该布局路由因此会被分派到authenticatedbundle其余路由进入unauthenticatedbundle。2.2 底层调用机制getBuildManifest真正执行分派的逻辑位于 vite/plugin.ts 的getBuildManifest取出reactRouterConfig中的{ routes, serverBundles, appDirectory }若未配置serverBundles直接返回{ routes }即单 bundle 形态否则遍历getAddressableRoutes(routes)见下文可寻址路由对每条路由用getRouteBranch向上回溯父级得到branch为每条路由调用serverBundles({ branch })把返回的 ID 记录进routeIdToServerBundleId将同一 ID 的入口文件路径登记进serverBundles映射。其中有两个细节值得注意传给函数的route.file是绝对路径——源码注释明确写着 Ensure absolute paths are passed to the serverBundles function见 plugin.ts便于你在函数内部直接fs.readFile(route.file)读取该路由的源文件做进一步处理集成测试正是这么做的见 vite-server-bundles-test.ts该函数支持异步类型为string | Promisestring源码中await serverBundles({ branch })也验证了这一点。3. branch 中每个 route 的属性serverBundles函数收到的branch是从根路由到当前路由的完整祖先链数组源码getRouteBranch通过逐级沿parentId回溯再反转得到见 plugin.ts。为了隔离实现细节框架只暴露了 4 个属性的子集定义见 config/config.ts属性类型说明idstring路由唯一 ID命名与其file一致相对 app 目录、去掉扩展名。例如app/routes/gists.$username.tsx的 id 为routes/gists.$usernamepathstring该路由用于匹配 URL pathname 的路径片段filestring该路由入口文件路径调用时被加工为以项目根为基准的绝对路径indexboolean该路由是否为 index 路由匹配父路径本身其中BranchRoute类型正是通过PickRouteManifestEntry, id | path | file | index实现只暴露子集的见 config/config.ts这也是为什么你在配置里拿不到parentId、loader等其余字段。3.1 可寻址路由哪些路由会触发 serverBundles文档明确指出serverBundles函数不会为不可寻址的路由如 pathless 布局路由单独调用。源码 plugin.ts 的getAddressableRoutes说明了取舍逻辑index 路由的父路由会被跳过——因为 index 路由接管了父路由的路径父路由本身没有可寻址的 URL没有path且不是 index 的路由即 pathless 布局会被跳过——它们只能经由后代路由被访问。也就是说真正的分派判断发生在每一条最终拥有独立 URL 的路由上而branch中仍然会携带祖先的 pathless 布局供你在判断逻辑里参考。4. Bundle ID 的硬性约束与产物目录serverBundleId并非任意字符串源码对其有两条校验规则见 plugin.ts返回值必须是string否则抛出The serverBundles function must return a string必须匹配正则/^[a-zA-Z0-9_]$/——仅允许字母、数字和下划线不允许连字符-。源码注释解释了原因Server bundle IDs must be valid Vite environment names, so hyphens are not allowed。也就是说这些 ID 会作为 Vite Environment服务端构建环境的名称使用因此必须遵循环境命名规则。产物结构上文档与测试共同确认bundle ID 会成为服务端构建目录下的子目录名每个 bundle 的入口文件位于build/server/bundleId/index.js。集成测试 vite-server-bundles-test.ts 对 manifest 的断言给出了真实输出示例{ serverBundles: { bundle_c: { id: bundle_c, file: build/server/bundle_c/index.js }, bundle_a: { id: bundle_a, file: build/server/bundle_a/index.js }, bundle_b: { id: bundle_b, file: build/server/bundle_b/index.js }, root: { id: root, file: build/server/root/index.js } } }注意文档提醒 Server Bundles 属于 framework 模式SSR下的能力。从源码看若关闭 SSRssr: falseserverBundles会被置空忽略config/config.ts同时当启用 RSCReact Server Components时配置校验会直接报错vite/rsc/plugin.ts 会把serverBundles加入错误清单——即Server Bundles 与 RSC 目前互斥。此外开发模式下不会为各 bundle 分别构建集成测试注释也说明dev 模式下没有 server bundles只是验证所有 bundle 的路由都可用见 vite-server-bundles-test.ts。5. 构建清单 Build Manifest 与 buildEnd 钩子构建完成后React Router 会调用配置中的buildEnd钩子并传入一个buildManifest对象供你在构建阶段把路由分发信息落盘或推送给上层路由系统。文档示例import type { Config } from react-router/dev/config; export default { // ... buildEnd: async ({ buildManifest }) { // ... }, } satisfies Config;buildEnd的完整签名含reactRouterConfig与viteConfig定义在 config/config.ts。当启用了 server bundles 时buildManifest会由ServerBundlesBuildManifest形态组成见 config/config.ts包含三个部分5.1serverBundlesBundle ID → 入口文件{ [serverBundleId: string]: { id: string; file: string } }映射每个 bundle ID 到它的唯一标识与产物入口文件相对项目根即上文展示的build/server/bundleId/index.js。可用于枚举部署产物清单。5.2routeIdToServerBundleId路由 → Bundle 反向索引Recordstring, string把每个可寻址路由的id映射到其所属 bundle ID。示例见 vite-server-bundles-test.ts{ routeIdToServerBundleId: { routes/_index: root, routes/bundle_a: bundle_a, routes/bundle_a._index: bundle_a, routes/bundle_a.route_a: bundle_a, routes/_pathless.bundle_c.route_a: bundle_c } }注意路径型路由如routes/_index与嵌套路由含 pathless 祖先都出现在映射中方便你按URL 最终归属直接查表。5.3routes完整路由清单一个将 route ID 映射到路由元数据的清单RouteManifest用于驱动上层自定义路由层决定这个 URL 该打到哪个 bundle。集成测试里的每条路由元数据形如见 vite-server-bundles-test.ts{ routes/bundle_a.route_a: { file: app/routes/bundle_a.route_a.tsx, id: routes/bundle_a.route_a, path: route_a, parentId: routes/bundle_a }, routes/bundle_a._index: { file: app/routes/bundle_a._index.tsx, id: routes/bundle_a._index, index: true, parentId: routes/bundle_a } }字段通常包含file、id、path、parentIdindex 路由额外带有index: true根路由为path: 、挂载在root下。这些元数据足以支撑一套URL 前缀 → 路由匹配 → bundle 入口的分发逻辑。在实际项目中你可以在buildEnd里把 manifest 序列化写入构建产物目录供运行时或部署管道消费——集成测试正是这样做的fs.promises.writeFile(build/test-manifest.json, JSON.stringify(buildManifest, null, 2))见 vite-server-bundles-test.ts。6. 自定义路由层的搭建思路与验证由于 React Router 官方构建产物只提供每个 bundle 各导出自己路由子集的 handlerURL 级别的分发完全交给你的上层路由层。设计上通常遵循两条原则每个 bundle 的 handler 只响应自己名下的路由。集成测试通过react-router/serve逐 bundle 启动产物入口路径形如build/server/bundleId/index.js见 integration/helpers/vite.ts验证访问本 bundle 路由正常渲染访问其他 bundle 的路由则得到 404见 vite-server-bundles-test.ts。这意味着你的路由层可以把404 即非我负责当作向后回退的信号。利用 buildManifest 做确定性分发。结合routes的路由元数据与routeIdToServerBundleId可以精确构造URL → 命中路由 → bundle 入口的映射表避免逐 bundle 试错。从源码结构看React Router 内置的 preview 服务器在遇到serverBundles时会加载全部 bundle 的 handler并按匹配深度最深优先排序后逐个尝试直到拿到非 404 响应为止见 vite/plugin.ts。这段实现可视为多 bundle 分发器的参考范式——它特别处理了非 index bundle 命中/时只渲染根路由的边界情况。你可以借鉴同一思路在自己的网关/入口服务里实现分发也可以选择完全基于 manifest 的确定性查表方案。7. 关键结论与适用前提适用模式仅 frameworkSSR模式ssr: false时配置会被忽略启用 RSC 时构建报错。配置位置react-router.config.ts 顶层的serverBundles函数类型定义见 config/config.ts。触发粒度仅可寻址路由会触发分派pathless 布局与 index 父路由不单独触发但会出现在branch中。返回值string | Promisestring仅限字母、数字、下划线Vite environment 名称约束每个返回值对应build/server/bundleId/index.js一个独立入口。消费方式通过buildEnd钩子读取buildManifest利用serverBundles、routeIdToServerBundleId、routes三张表驱动自定义路由分发层。分发责任React Router 负责按你的规则拆产物 暴露清单URL 级路由分发由宿主平台的前置路由层负责。如果你正在做边缘平台Edge/FaaS集成或需要让不同分区应用独立部署、独立扩缩容Server Bundles 配合buildEnd中的 manifest 即可构成一套自洽的多入口 分发元数据方案单 server 部署的中小型应用则完全不需要启用它。更多相关背景可参阅 如何选择 SPA / Framework 模式 与 react-router.config.ts 参考。【免费下载链接】react-routerDeclarative routing for React项目地址: https://gitcode.com/GitHub_Trending/re/react-router创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考