服务端渲染（SSR）的类型适配

在现代前端开发中，服务端渲染（Server-Side Rendering，简称SSR）已成为提升应用性能和SEO友好性的关键技术。当我们将TypeScript与主流前端框架（如React、Vue、Angular等）结合使用时，类型系统能为SSR带来显著的开发体验提升和运行时安全性保障。本文将深入探讨如何在SSR场景下实现完美的类型适配。

一、SSR中的类型挑战

服务端渲染环境与纯客户端渲染(CSR)相比，在类型系统上存在一些独特挑战：

环境差异：Node.js与浏览器环境的API差异
数据流类型：服务器预取数据到客户端的水合过程
生命周期差异：组件在服务端和客户端的不同行为
全局变量访问：如window、document等浏览器特有对象

二、基础类型适配策略

1. 环境区分类型

typescript 复制代码

declare const __SERVER__: boolean;

if (__SERVER__) {
  // 服务端特有逻辑
  const serverModule = require('server-only-module');
} else {
  // 客户端特有逻辑
  const clientModule = require('client-only-module');
}

2. 同构代码类型保护

typescript 复制代码

const safeWindow = typeof window !== 'undefined' ? window : null;
const safeDocument = typeof document !== 'undefined' ? document : null;

三、框架特定的类型适配方案

1. React + Next.js/Nuxt.js

页面Props类型定义：

typescript 复制代码

import { GetServerSideProps } from 'next';

interface PageProps {
  user: {
    id: string;
    name: string;
  };
  timestamp: number;
}

export const getServerSideProps: GetServerSideProps<PageProps> = async () => {
  const data = await fetchUserData();
  return {
    props: {
      user: data.user,
      timestamp: Date.now()
    }
  };
};

const PageComponent: React.FC<PageProps> = ({ user, timestamp }) => {
  // 组件实现
};

2. Vue + Nuxt.js

组合式API类型：

typescript 复制代码

<script setup lang="ts">
interface AsyncData {
  posts: Post[];
  total: number;
}

const { data } = await useAsyncData<AsyncData>('posts', () => {
  return $fetch('/api/posts');
});
</script>

3. Angular Universal

平台感知服务：

typescript 复制代码

import { PLATFORM_ID, Inject } from '@angular/core';
import { isPlatformBrowser, isPlatformServer } from '@angular/common';

@Injectable()
export class StorageService {
  constructor(@Inject(PLATFORM_ID) private platformId: Object) {}

  getItem(key: string): string | null {
    if (isPlatformBrowser(this.platformId)) {
      return localStorage.getItem(key);
    }
    return null;
  }
}

四、高级类型模式

1. 同构路由类型

typescript 复制代码

type RouteParams<T extends string> = 
  T extends `${infer Start}:${infer Param}/${infer Rest}`
    ? { [K in Param | keyof RouteParams<Rest>]: string }
    : T extends `${infer Start}:${infer Param}`
    ? { [K in Param]: string }
    : {};

function useParams<T extends string>(path: T): RouteParams<T> {
  // 实现逻辑
}

// 使用示例
const params = useParams('/user/:id/posts/:postId');
// params 类型为 { id: string; postId: string }

2. 服务端/客户端差异化组件

typescript 复制代码

interface CommonProps {
  children: React.ReactNode;
}

interface ClientOnlyProps extends CommonProps {
  fallback?: React.ReactNode;
}

const ClientOnly: React.FC<ClientOnlyProps> = ({ children, fallback = null }) => {
  const [mounted, setMounted] = useState(false);

  useEffect(() => {
    setMounted(true);
  }, []);

  if (!mounted && __SERVER__) {
    return fallback;
  }

  return <>{children}</>;
};

五、测试与验证策略

类型测试工具：

typescript 复制代码

import { expectTypeOf } from 'expect-type';

expectTypeOf(getServerSideProps).returns.toEqualTypeOf<
  Promise<{ props: PageProps }>
>();

端到端类型检查：
- 在CI流程中添加类型检查步骤
- 使用tsc --noEmit验证类型正确性
- 针对SSR和CSR分别建立类型测试用例

六、最佳实践总结

明确区分环境类型：严格分离服务端和客户端类型定义
统一数据契约：确保服务器预取数据与客户端期望类型一致
渐进增强类型：从基础类型开始，逐步添加复杂类型约束
类型文档化：为SSR特定类型添加详细注释
性能考量：避免过度复杂的类型影响编译速度

结语

TypeScript与SSR的结合为大型前端应用提供了类型安全的开发体验。通过合理的类型设计，我们能够在编译期捕获大量潜在问题，显著降低运行时错误概率。随着前端框架对TypeScript支持度的不断提升，SSR类型适配已成为现代前端架构中不可或缺的一环。掌握这些技巧，将帮助开发者构建更健壮、更易维护的同构应用。