react-router-v7-spa-mode-tailwindcss

React Router v7 SPA 模式下的 Tailwind CSS 配置与原理

在 React Router v7 的 SPA 模式（ssr: false）下，如果直接使用 import './app.css' 引入 Tailwind CSS，可能会在生产环境打包（Production Build）中遇到样式丢失的问题。本文记录了该问题的解决方案及其背后的原理。

1. 问题现象

开发环境：样式正常。
生产环境：运行 npm run build 后，生成的 index.html 中缺少 CSS <link> 标签，导致页面无样式。
原因：在 SPA 模式下，React Router 需要通过 HydrateFallback 组件来生成初始的 HTML 骨架。如果没有正确配置 links 导出或 HydrateFallback，框架无法将样式注入到入口 HTML 中。

2. 解决方案

步骤一：使用 `links` 导出 CSS

将全局样式从直接 import 改为通过 links 函数导出。

修改 app/root.tsx：

import {
  // ... 其他导入
  type LinksFunction,
} from 'react-router';

// 1. 使用 ?url 后缀导入 CSS 文件路径
import appStyles from './app.css?url';

// 2. 导出 links 函数
export const links: LinksFunction = () => [
  { rel: "stylesheet", href: appStyles },
];

步骤二：配置 `HydrateFallback`

在 root.tsx 中导出 HydrateFallback 组件。这是 SPA 模式的关键，React Router 会使用此组件渲染 index.html。

修改 app/root.tsx：

import { Links, Meta, Scripts } from 'react-router';

// ... links 导出 ...

// 3. 导出 HydrateFallback 组件
export function HydrateFallback() {
  return (
    <html lang="en">
      <head>
        <meta charSet="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1" />
        <Meta />
        {/* 关键：确保 <Links /> 被渲染，这样 CSS 链接才会被注入 */}
        <Links />
      </head>
      <body>
        {/* 注入脚本 */}
        <Scripts />
      </body>
    </html>
  );
}

// ... Root 组件 ...

步骤三：清理构建脚本

如果之前使用了额外的脚本（如 inject-css.js）来手动注入 CSS，现在可以安全地移除它，并恢复标准的构建命令。

修改 package.json：

"scripts": {
  "build": "react-router build"
}

3. 原理分析：为什么是 `export const links`？

这是 React Router 的 约定式路由 API (Route Module API)。

自动识别机制

框架会自动扫描路由文件（如 root.tsx）中的特定命名导出（Named Exports）。只要按照约定命名，框架就会自动提取并使用它们。

links: 用于定义 <link> 标签（CSS、Favicon 等）。
meta: 用于定义 <meta> 标签（SEO 标题、描述）。
loader: 数据加载函数。

`<Links />` 组件的作用

在组件树中渲染 <Links /> 组件时，React Router 会：

遍历当前激活的所有路由层级（例如 Root -> Layout -> Page）。
收集每个路由模块导出的 links 函数返回值。
将它们合并并渲染为 HTML 的 <link> 标签。

相比直接 `import` 的优势

按需加载：子路由导出的 links 只有在访问该路由时才会加载，减少首屏资源大小。
层级控制：框架确保父路由样式先加载，子路由样式后加载，便于样式覆盖。
声明式管理：更符合 React Router 的数据流和生命周期管理。

登录到 YUJIMAKA