React Router Framework Mode 部署指南全栈托管与静态托管实战【免费下载链接】react-routerDeclarative routing for React项目地址: https://gitcode.com/GitHub_Trending/re/react-router导读本文以 React Router Framework Mode 的官方部署指南docs/start/framework/deploying.md为骨架系统讲解 React Router 应用的两种部署形态——需要运行时的全栈托管与无需服务器的静态托管。你将掌握官方模板的选型与脚手架命令、部署产物build/client与build/server的含义、react-router/serve与自定义 Express 服务器的用法以及不同渲染策略SSR / SPA / 预渲染对应的托管配置最终能够把应用正确部署到 Docker、Serverless 或纯静态文件托管平台。部署模型总览先确定你要哪种「托管」与绝大多数 Web 框架不同React Router 并不要求你为「部署」预先站队。在 Framework Mode框架模式 下同一份代码可以根据你的需求编译成两种形态分别对应两类托管方式部署形态托管方式前提能力典型产物Fullstack Hosting全栈托管平台运行你的 Node.js / 运行时进程启用 Server Rendering默认ssr: truebuild/server服务端构建build/client静态资源Static Hosting静态托管纯静态文件服务器 / CDN关闭运行时 SSRssr: false可能叠加预渲染仅build/clientHTML 静态资源 .data载荷官方建议这样理解两者关系当部署到静态托管时你可以把 React Router 当作任何其他「带 React 的单页应用」一样处理引用自部署文档引言。也就是说路由逻辑本身不依赖特定服务器差异全部来自「页面 HTML 由谁生成、在何时生成」。在开始部署之前请先完成应用创建并阅读脚手架输出的 README官方部署文档也特别提醒执行完create-react-router后务必遵循模板 README 中的指引。入门方式参见 Framework Mode 安装指南npx create-react-routerlatest my-react-router-app cd my-react-router-app npm i npm run dev # 开发地址 http://localhost:5173关键前提搞懂一次构建会产出什么Framework Mode 把 Data Mode 与 Vite 插件打包在一起docs/start/framework/index.md并通过react-router build产出可部署的目录结构。以仓库内的 playground/framework/package.json 为参考典型项目脚本如下scripts: { build: react-router build, dev: react-router dev, start: react-router-serve ./build/server/index.js }其中build/client存放静态资源与 HTML用于浏览器与 CDNbuild/server存放服务端运行时代码。这与 react-router.config.ts 中的三个选项直接相关appDirectory应用代码目录默认appbuildDirectory构建产物目录默认build全部产物都位于其下serverBuildFile服务端构建输出文件名默认index.js这个文件最终要被部署到你的服务器上serverModuleFormat服务端构建模块格式默认esm可设cjsssr是否启用服务端渲染默认true。值得注意的部署原则见于react-router/serve文档 docs/api/other-api/serve.md生产环境只需要部署构建产物build/react-router.config.ts本身并不保证在生产可用所以运行时服务器必须通过命令行参数或配置显式告知服务端构建位置而不是依赖配置文件的读取。部署形态 1全栈托管Fullstack Hosting如果启用运行时 SSR即默认的ssr: true详见 渲染策略文档页面 HTML 由服务器在请求到达时即时渲染因此需要能长期运行 Node.js 进程的平台。React Router 为此提供两条路径路径 A使用官方 App Serverreact-router/serveReact Router 的设计哲学是「你自己的服务器由你自己掌控」但如果你不想自行搭建服务器可以直接使用这个基于 Express 的生产级 Node.js 服务器npm install react-router/serve react-router-serve server-build-path # 例如 react-router-serve build/server/index.js它的实现位于 packages/react-router-serve/cli.tspackage.json 中声明了bin: { react-router-serve: bin.cjs }并通过engines.node 22.22.0约束运行环境。从源码可以确认其默认行为未显式设置时强制NODE_ENV productioncli.ts 第 16 行端口优先取process.env.PORT默认探测3000端口第 132-134 行可通过process.env.HOST指定监听主机名第 227-229 行会将其传给app.listen按内容是否可变的规则挂载静态资源/assets使用immutable: true与maxAge: 1y其余客户端资源走express.staticpublic/目录缓存 1 小时并额外支持/.well-known目录第 200-212 行启用compression压缩与morgan(tiny)访问日志第 195、213 行将剩余请求交给createRequestHandler处理响应SIGTERM/SIGINT信号优雅关闭第 215-233 行。开发者若需要定制底层 Express 服务器官方文档 serve.md 的立场很明确不要通过参数去扩展 App Server而是迁移到react-router/express适配器见下。路径 B用react-router/express编写自定义服务器当你需要中间件、鉴权、日志、限流等控制能力时官方 Node Docker 模板正是这种形态。仓库内已有对应适配器实现 packages/react-router-express/server.ts其接入方式在 adapter.md 有完整说明核心模式是import express from express; import { createRequestHandler } from react-router/express; import type { ServerBuild } from react-router; export const app express(); async function getBuild() { let build: ServerBuild await import(virtual:react-router/server-build); return build; } app.use(createRequestHandler({ build: await getBuild() }));部署文档将这类全栈应用描述为「容器化应用可部署到任何支持 Docker 的平台」并明确点名下列平台AWS ECS、Google Cloud Run、Azure Container Apps、Digital Ocean App Platform、Fly.io、Railway。无论选哪家容器内都需要一个启动进程通常是node ./build/server/index.js或react-router-serve ./build/server/index.js并正确注入PORT与NODE_ENV。此外全栈托管不止 Node 一种运行时。仓库同时维护了面向不同边缘/无服务器环境的适配器包可作为自行接入平台的参考react-router-cloudflare 及其 worker.ts面向 Cloudflare Workers 运行时react-router-node提供 Node 运行时下createCookieSessionStorage、流式响应等能力react-router-architect面向 AWS Architect 风格部署react-router-serve即上文 App Server。这些集成均有对应的集成测试覆盖例如仓库中的 integration/vite-plugin-cloudflare-test.ts 与 integration/react-router-serve-test.ts可作为理解各平台适配行为的参考。部署形态 2静态托管Static Hosting如果你的内容不需要每次请求都走服务器可以把构建产物直接丢给任何静态文件服务器或 CDN。这一步需要先理解渲染策略之间的转换关系详见 渲染策略 与 预渲染指南SPA Mode纯 SPA在react-router.config.ts中设置ssr: falseimport type { Config } from react-router/dev/config; export default { ssr: false, } satisfies Config;这会禁用运行时服务端渲染但 React Router 仍会在构建期把根路由渲染成index.html官方文档 SPA 指南 将其描述为「比空div更有意义的 SPA」随后把build/client目录部署到任意静态托管平台。受此影响由于不再有运行时代码服务器全应用只有根路由可挂loader构建期调用其余路由应使用clientLoader/clientAction管理数据与变更部署文档对静态托管给出与任何 SPA 相同的核心要求把一切 URL 指向index.html否则在有效路由上访问会得到 404。不同平台做法不同有些默认支持有些不支持例如支持_redirects文件的平台可以写/* /index.html 200预渲染Pre-rendering叠加如果希望部分页面获得纯静态 HTML利于 SEO 与首屏性能可继续叠加prerender配置。预渲染是构建期操作框架创建new Request()并像真实服务器一样跑过你的应用为每个路径生成两个文件见 pre-rendering.md[url].html首屏文档请求使用[url].data客户端导航SPA 内跳转的数据请求使用。当ssr: false但只想预渲染部分路径时框架会额外输出一个 SPA Fallback 文件用于兜底未预渲染的路径——若未预渲染/兜底文件是build/client/index.html若已预渲染/则兜底文件为build/client/__spa-fallback.html可按需配置重定向规则。ssr: false下全站路由不允许出现action/headers没有运行时服务器执行它们构建期会直接报错拦截此类误用。用官方模板快速启动附完整清单部署文档给出两类起步方式先跑模板命令再按 README 操作。其中三个模板会生成可直接容器化Docker的应用其余平台则由对应厂商维护独立模板/指南。下面完整收录官方部署文档中的模板清单。Node.js Docker默认模板npx create-react-routerlatest --template remix-run/react-router-templates/default模板能力Server Rendering服务端渲染Tailwind CSSNode Docker自定义 Express 服务器npx create-react-routerlatest --template remix-run/react-router-templates/node-custom-server模板能力Server RenderingTailwind CSS自定义 express server便于在运行层获得更多控制权Node Docker Postgresnpx create-react-routerlatest --template remix-run/react-router-templates/node-postgres模板能力Server Rendering使用 Drizzle 连接 Postgres 数据库Tailwind CSS自定义 express server便于在运行层获得更多控制权上述三种模板产出的容器化应用都可部署到前文列出的任意 Docker 平台AWS ECS、Google Cloud Run、Azure Container Apps、Digital Ocean App Platform、Fly.io、Railway。模板脚手架逻辑本身在仓库中可查create-react-router的 CLI 位于 packages/create-react-router/cli.ts其--template参数会拉取指定模板并执行复制集成测试的模板夹具可在 integration/helpers/templates.ts 与各 vite 模板目录中看到。由各平台厂商维护的模板与指南部署文档指出以下平台各自维护面向 React Router 的官方模板/部署指南应用可参照对应文档接入下列信息来自部署文档对厂商能力的表述具体接入步骤以各平台当时发布的指南为准Vercel维护官方 React Router 模板与接入指南Cloudflare WorkersCloudflare 维护官方 React Router 模板Workers 运行时可直接运行基于请求/响应的应用仓库配套的 react-router-cloudflare 包与 集成测试 展示了其运行形态NetlifyNetlify 维护官方 React Router 模板支持在 Netlify 构建流程中识别框架并部署EdgeOne Pages维护官方 React Router 模板与指南DeployHQ提供将 React Router 部署到自有服务器的操作指南例如由 GitHub 触发构建再部署Hostinger托管 Node.js 环境支持带服务端渲染的 React Router 应用并支持从 GitHub 自动部署。一个值得知道的落地技巧多数厂商模板都会在底层引入react-router.config.ts的presets选项。该选项用于注入面向特定平台的插件预设见 react-router.config.ts 的presets说明与 预置指南使同一份配置在不同平台的部署差异被收敛到预设层而不是散落在业务代码中。部署决策速查与自检清单把部署文档的要点收敛成一张决策表你的诉求配置托管部署注意点首屏需要实时数据、需要运行时action/headersssr: true默认全栈托管Node 进程 / Workers使用react-router-serve或react-router/express注入PORT、HOST、NODE_ENV纯客户端应用无服务器需求ssr: false静态托管部署build/client把全部 URL 指向index.html静态内容加速 少量动态页ssr: falseprerender部分路径静态托管部署产物含[url].html/[url].data未预渲染路径走 SPA FallbackSSR 为主、个别路径要缓存提速ssr: trueprerender全栈托管预渲染路径命中静态文件其余照常 SSR详见 pre-rendering.md上线前最后核对以下事项运行环境变量全栈场景下确认PORTApp Server 默认 3000、HOST、NODE_ENV已正确设置——App Server 在未设置NODE_ENV时会强制为production见 cli.ts只部署构建产物生产环境需要build/client与build/server或按serverBuildFile重命名的服务端入口开发期文件与react-router.config.ts不应出现在产物中静态托管 404 检查如果「有效路由」返回 404通常意味着托管方没有把未知 URL 回退到index.html或 SPA Fallback需按平台规则配置重写如_redirects静态资源缓存/assets资源带 hash 且不可变适合immutable maxAge长缓存可参考 App Server 的默认静态中间件行为cli.ts。延伸阅读渲染策略总览CSR / SSR / 静态预渲染docs/start/framework/rendering.mdSPA Mode 完整说明ssr:false行为与根路由限制docs/how-to/spa.md预渲染配置prerender布尔值 / 路径数组 / 函数 / 并发控制docs/how-to/pre-rendering.mdreact-router.config.ts全部选项部署目录、构建格式、SPA 开关等docs/api/framework-conventions/react-router.config.ts.md官方 App Server 的用法、PORT/HOST与迁移到自定义服务器的说明docs/api/other-api/serve.mdExpress 适配器自定义服务器接入docs/api/other-api/adapter.mdApp Server 源码Express 中间件与静态资源行为packages/react-router-serve/cli.ts【免费下载链接】react-routerDeclarative routing for React项目地址: https://gitcode.com/GitHub_Trending/re/react-router创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考