Fluent UI React Components 在 Remix 框架下的服务端渲染实践

2025-05-11 00:42:59作者：曹令琨Iris

本文将详细介绍如何在 Remix 框架中实现 Fluent UI React Components（v9）的服务端渲染（SSR）方案。作为微软开源的现代化 UI 组件库，Fluent UI 在服务端渲染场景下需要特殊配置才能完美运行。

核心原理

Fluent UI v9 版本采用了 CSS-in-JS 的样式方案，这在服务端渲染时需要考虑两个关键点：

样式提取：需要在服务端收集所有组件的样式并注入到 HTML 中
水合过程：确保客户端能够正确接管服务端渲染的 DOM 结构

环境准备

首先需要安装必要的依赖包：

# 使用 yarn
yarn add @fluentui/react-components isbot
yarn add -D vite vite-plugin-cjs-interop

# 使用 npm
npm install @fluentui/react-components isbot
npm install -D vite vite-plugin-cjs-interop

Vite 配置调整

由于 Fluent UI 使用 CommonJS 模块格式，需要通过插件进行转换：

import { defineConfig } from 'vite'
import { cjsInterop } from 'vite-plugin-cjs-interop'

export default defineConfig({
  ssr: {
    noExternal: ['@fluentui/react-icons']
  },
  plugins: [
    cjsInterop({
      dependencies: [
        '@fluentui/react-components',
        '@fluentui/react-nav-preview',
        '@fluentui/react-list-preview',
        '@fluentui/react-virtualizer',
        '@fluentui/react-motion-components-preview'
      ]
    })
  ]
})

服务端入口改造

关键的服务端渲染逻辑集中在 entry.server.tsx 文件中：

import { 
  createDOMRenderer,
  RendererProvider,
  renderToStyleElements,
  SSRProvider
} from '@fluentui/react-components'

export default function handleRequest(
  request: Request,
  responseStatusCode: number,
  responseHeaders: Headers,
  remixContext: EntryContext
) {
  const renderer = createDOMRenderer()
  
  return new Promise((resolve, reject) => {
    const { pipe, abort } = renderToPipeableStream(
      <RendererProvider renderer={renderer}>
        <SSRProvider>
          <RemixServer context={remixContext} url={request.url} />
        </SSRProvider>
      </RendererProvider>,
      {
        onShellReady: () => {
          const body = new PassThrough({
            transform(chunk, _, callback) {
              // 处理样式注入逻辑
              const style = renderToStaticMarkup(
                <>{renderToStyleElements(renderer)}</>
              )
              chunk = chunk.toString().replace('__STYLES__', style)
              callback(null, chunk)
            }
          })
          
          responseHeaders.set('Content-Type', 'text/html')
          resolve(new Response(stream, { headers: responseHeaders }))
          pipe(body)
        }
      }
    )
  })
}

客户端入口优化

客户端入口文件 entry.client.tsx 需要进行渐进式水合：

import { RemixBrowser } from '@remix-run/react'
import { startTransition, StrictMode } from 'react'
import { hydrateRoot } from 'react-dom/client'

const hydrate = async () => {
  startTransition(() => {
    hydrateRoot(
      document,
      <StrictMode>
        <RemixBrowser />
      </StrictMode>
    )
  })
}

// 使用空闲回调优化性能
if (window.requestIdleCallback) {
  window.requestIdleCallback(hydrate)
} else {
  window.setTimeout(hydrate, 1)
}

根组件配置

在根组件中需要处理样式占位符和主题提供：

import { FluentProvider, webLightTheme } from '@fluentui/react-components'

export function Layout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <head>
        {/* 服务端渲染时插入样式 */}
        {!isBrowser() && '__STYLES__'}
      </head>
      <body>
        <FluentProvider theme={webLightTheme}>
          {children}
        </FluentProvider>
      </body>
    </html>
  )
}

常见问题解决

样式闪烁问题：确保样式提取和注入的时机正确，避免客户端重新计算样式
水合不匹配：检查服务端和客户端渲染结果的一致性
性能优化：使用 requestIdleCallback 可以改善大型应用的加载体验

开发注意事项

在开发过程中，某些浏览器扩展（如 Microsoft Editor）可能会干扰 Fluent UI 的样式注入机制，导致开发服务器不断重启。建议在开发时禁用这类扩展，或使用无痕模式进行开发。

通过以上配置，开发者可以在 Remix 框架中充分利用 Fluent UI React Components 的强大功能，同时享受服务端渲染带来的 SEO 优势和首屏性能提升。

登录后查看全文