# TanStack Router SSR/SSG 最佳实践指南 (Cloudflare Pages 版)

本文档基于生产环境验证的架构，提炼了使用 TanStack Router 进行 SSR/SSG 混合部署的通用最佳实践。本方案特别针对 Cloudflare Pages 平台进行了优化，旨在实现高性能、高 SEO 友好度且低维护成本的现代 Web 应用。

---

## 1. 核心架构设计：静态优先，动态兜底 (Hybrid Architecture)

### 1.1 设计理念
- **默认静态 (SSG)**：对所有公开、内容相对固定的页面（营销页、博客、文档）进行构建期预渲染。这保证了最佳的 TTFB（首字节时间）和 CDN 缓存能力。
- **SSR 兜底 (SSR Fallback)**：仅对无法预渲染的长尾路径或需要实时数据的 SEO 页面启用运行时服务端渲染。
- **客户端渲染 (CSR)**：对需要登录状态、高度交互的应用内页面（Dashboard、设置），直接降级为 SPA 模式，无需 SSR。

### 1.2 URL 分层策略
| 路由类型 | 渲染模式 | 适用场景 | 示例 |
| :--- | :--- | :--- | :--- |
| **强静态** | SSG (预渲染) | 首页、关于我们、法律条款 | `/`, `/about` |
| **内容流** | SSG + ISR* | 博客文章、产品详情 | `/blog/$slug` |
| **应用态** | CSR (SPA) | 用户后台、购物车 | `/dashboard/*` |
| **动态 SEO** | SSR | 搜索结果、即时生成的落地页 | `/search`, `/promo/$id` |

> *注：Cloudflare Pages 暂不支持增量静态再生 (ISR)，通常通过“预渲染 + 定时重建”或“预渲染首屏 + 客户端数据更新”替代。

---

## 2. 路由系统改造 (Router Refactoring)

### 2.1 工厂模式 (Factory Pattern)
在 SSR 环境下，**必须**避免单例模式。每个请求都需要独立的 Router 实例，以防止跨请求的状态污染。

```tsx
// ❌ 错误：单例模式
export const router = createRouter({ ... })

// ✅ 正确：工厂模式
export function createRouter() {
  return createRouter({
    routeTree,
    context: { ... }, // 注入请求级上下文
  })
}
```

### 2.2 入口分离
标准的 SSR 架构需要拆分客户端和服务端入口：

- **`entry-client.tsx`**：负责客户端“注水” (Hydration)。
  ```tsx
  const router = createRouter()
  router.hydrate() // 恢复服务端状态
  ReactDOM.hydrateRoot(document.getElementById('root')!, <RouterProvider router={router} />)
  ```

- **`entry-server.tsx`**：负责服务端渲染与脱水 (Dehydration)。
  ```tsx
  export async function render(url, headAssets) {
    const router = createRouter()
    const memoryHistory = createMemoryHistory({ initialEntries: [url] })
    router.update({ history: memoryHistory })
    
    await router.load() // 等待关键数据加载
    
    // 注入 Head 资源并渲染
    // 返回 { appHtml, dehydratedRouter }
  }
  ```

---

## 3. Cloudflare Functions 集成 (The Critical Part)

### 3.1 构建期生成入口 (Build-time Generation)
不要手动维护 `functions/[[path]].ts`。应在构建脚本中动态生成它，以便将 `index.html` 中带有哈希的文件名（如 `assets/index-Ah3...css`）自动注入到 SSR 模板中。

**流程**：
1. 构建客户端 (`vite build`) → 产出 `dist/client` (含带哈希的静态资源)。
2. 构建服务端 (`vite build --ssr`) → 产出 `dist/server`。
3. **脚本生成 Functions 入口**：读取 `dist/client/index.html` 提取 CSS/JS 标签，写入 `functions/[[path]].ts`。

### 3.2 静态资源绕行 (Static Bypass) - **核心稳定性机制**
SSR 最常见的问题是错误地拦截了静态资源请求（如 `.css`, `.js`, `robots.txt`），导致返回 HTML 内容，引发 MIME 类型错误或 React Hydration 错误 (Error 418)。

**最佳实践逻辑**：
```typescript
// functions/[[path]].ts
export const onRequest = async (context) => {
  const { pathname } = new URL(context.request.url);
  const accept = context.request.headers.get('accept') || '';
  
  // 1. 扩展名检查：任何带扩展名的请求视为静态资源
  const hasExt = /\/[^/]+\.[^/]+$/.test(pathname);
  
  // 2. Accept 头检查：不接受 HTML 的请求视为非页面请求
  const acceptsHtml = /\btext\/html\b/i.test(accept);
  
  // 3. 绕行判断：非 GET、有扩展名、或不接受 HTML -> 直接透传给静态层
  if (context.request.method !== 'GET' || hasExt || !acceptsHtml) {
    return context.next();
  }
  
  // ... 进入 SSR 逻辑
}
```

### 3.3 SSR 路由白名单 (Gating)
为了防止 404 页面或未知的 SPA 路由意外触发 SSR（导致不必要的计算开销或错误），建议引入**SSR 路径白名单**。

- **机制**：利用 `prerender-routes.json` 或 `sitemap` 作为白名单。
- **逻辑**：如果请求路径不在白名单中，跳过 SSR，直接返回 SPA 的 `index.html`（由 Cloudflare 默认行为处理）。

---

## 4. SEO 与 Head 管理

### 4.1 集中式 Head 策略
利用 TanStack Router 的 Context 功能，在根路由 (`__root.tsx`) 统一管理全局 SEO 标签。

- **Hreflang & Canonical**：基于当前 URL 动态生成，避免在每个页面重复手动配置。
- **Title & Description**：通过 `loader` 获取数据，通过 `head` 函数返回。

### 4.2 避免 Hydration Mismatch
服务端生成的 Title/Meta 必须与客户端初始渲染完全一致。
- **技巧**：不要在组件内部使用 `useEffect` 修改 Title。使用 Router 的 `head` 属性，它能确保服务端渲染时就输出正确的 `<title>` 标签。

---

## 5. 构建与部署管道 (Pipeline)

### 5.1 推荐构建顺序
1. **`build:client`**：生成静态产物。
2. **`build:server`**：生成 SSR 渲染器。
3. **`generate:functions`**：生成 Cloudflare Functions 入口（注入 CSS/JS）。
4. **`prerender`**：本地运行 SSR 渲染器，生成高优先级路由的静态 HTML 文件。
5. **`post-build`**：
   - 生成 `sitemap.xml` 和 `robots.txt`。
   - 生成 `_redirects` 规则文件。
   - 清理 HTML 中的开发时标签（如 `/src/*`）。

### 5.2 重定向规则 (`_redirects`)
对于 Cloudflare Pages，正确的重定向规则是性能和稳定性的关键。

```plaintext
# 1. 静态资源优先 (防止 SSR 误拦截)
/assets/*  /assets/:splat  200
/images/*  /images/:splat  200

# 2. 规范化规则 (移除尾随斜杠等)
# 注意：不要强制添加尾随斜杠，这会破坏文件请求

# 3. SPA 兜底 (对于未被 SSR/SSG 覆盖的路径)
/*  /index.html  200
```

---

## 6. 常见故障排查 (Troubleshooting)

| 现象 | 可能原因 | 解决方案 |
| :--- | :--- | :--- |
| **CSS/JS 报 MIME 错误** | SSR 拦截了静态资源并返回了 HTML | 检查 `onRequest` 中的**静态资源绕行**逻辑；检查 `_redirects` 是否有强制重写规则。 |
| **React Error #418** | 服务端 HTML 与客户端渲染不一致 | 检查 `entry-server` 是否注入了正确的脱水数据；检查是否有组件使用了 `window` 变量但未做环境判断。 |
| **页面空白 / 307 跳转** | 路由初始化 URL 不正确 | 确保服务端传入 `createMemoryHistory` 的 URL 是规范化的（包含 pathname + search）。 |
| **样式闪烁 (FOUC)** | CSS 未在 HTML 头部注入 | 确保 `generate:functions` 脚本正确提取了 `index.html` 中的 `<link rel="stylesheet">` 并注入到 SSR 模板中。 |

---

## 7. 总结
本方案的核心优势在于**确定性**：
1. **构建确定性**：通过构建脚本注入哈希资源，杜绝版本不一致。
2. **路由确定性**：通过白名单和静态绕行，确保 SSR 只在应该发生的时候发生。
3. **SEO 确定性**：通过集中式 Head 管理，保证元数据的准确输出。


本文档基于生产环境验证的架构，提炼了使用 TanStack Router 进行 SSR/SSG 混合部署的通用最佳实践。本方案特别针对 Cloudflare Pages 平台进行了优化，旨在实现高性能、高 SEO 友好度且低维护成本的现代 Web 应用。

TanStack Router SSR/SSG 最佳实践指南 (Cloudflare Pages 版)

前端

云计算

本文分享TanStackRouter在Cloudflare Pages平台的SSR/SSG混合部署最佳实践，涵盖架构设计、路由改造、Functions集成等核心方案，实现高性能、SEO友好的Web应用。重点介绍静态资源绕行、SSR白名单等关键优化策略，解决常见部署问题。

路由

2026新春采购季

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

TanStack Router SSR/SSG 最佳实践指南 (Cloudflare Pages 版)-腾讯云开发者社区-腾讯云

TanStack Router SSR/SSG 最佳实践指南 (Cloudflare Pages 版)

TanStack Router SSR/SSG 最佳实践指南 (Cloudflare Pages 版)

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐