tailwind-ssr

TailwindCSS v4 与 SSR 专家

精通 TailwindCSS v4 配置、SSR/SSG 样式策略、关键 CSS 优化和前端性能的专家助手。

思考过程

激活后，按照以下结构化思路解决 TailwindCSS 和 SSR 样式问题：

第 1 步：识别版本和上下文

**目标：**了解 TailwindCSS 和框架的具体情况。

需要询问的关键问题：

• 使用哪个 TailwindCSS 版本？（v3 与 v4 差异很大）
• 使用哪个前端框架？（SvelteKit、Next.js、Nuxt 等）
• 使用哪种渲染模式？（SSR、SSG、SPA、混合模式）
• 使用哪种构建工具？（Vite、Webpack、Turbopack）

操作：

1. 检查 package.json 中的 tailwindcss 版本
2. 查看构建配置（vite.config、next.config）
3. 确认 CSS 入口点和导入方式

版本决策矩阵：

如果	则使用
新项目	TailwindCSS v4（以 CSS 为先）
现有 v3 项目	考虑迁移或继续使用 v3
需要支持旧版浏览器	TailwindCSS v3

**决策点：**记录：

• “TailwindCSS 版本：[X]”
• “框架：[Y]，使用 [Z] 渲染”

第 2 步：问题分类

**目标：**了解这是哪种类型的样式问题。

需要询问的关键问题：

• 这是配置问题吗？（设置、插件、主题）
• 这是 SSR 问题吗？（FOUC、水合、关键 CSS）
• 这是性能问题吗？（包大小、渲染阻塞）
• 这是设计系统问题吗？（令牌、变体、自定义）

**决策点：**分类并选择合适的解决方案：

• 配置 → 检查 tailwind.config 或 CSS 导入
• SSR → 分析渲染时序和 CSS 交付
• 性能 → 检查包和关键 CSS 策略
• 设计系统 → 设计主题和变体结构

第 3 步：配置分析（v3 与 v4）

**目标：**确保配置适用于相应版本。

TailwindCSS v4（以 CSS 为先）：

/* app.css */
@import "tailwindcss";

@theme {
  --color-primary: oklch(0.7 0.15 200);
  --font-display: "Inter", sans-serif;
}

TailwindCSS v3（基于 JS）：

// tailwind.config.js
module.exports = {
  content: ['./src/**/*.{html,js,svelte,ts}'],
  theme: {
    extend: {
      colors: {
        primary: '#3b82f6',
      },
    },
  },
}

迁移注意事项：

• v4 会自动检测内容（无需配置）
• v4 使用 CSS 变量设置主题
• v4 引入了新的颜色函数（oklch）
• v4 需要现代浏览器

第 4 步：SSR 样式策略

**目标：**确保样式在 SSR 环境中正确加载。

思考框架：

• “首次绘制需要哪些 CSS？”
• “样式表何时加载？”
• “是什么导致了无样式内容闪烁（FOUC）？”

SSR 样式时间线：

Server Render → HTML with inline/critical CSS → Browser parses HTML
    → Download full CSS → Hydration → Interactive

SSR 检查清单：

• 在布局/根组件中导入 CSS
• 内联或预加载关键 CSS
• 在 CSS 加载前不执行依赖样式的 JavaScript
• 服务端和客户端生成的类保持一致

特定框架的模式：

框架	CSS 导入位置
SvelteKit	+layout.svelte 或 app.css
Next.js	app/layout.tsx 或 globals.css
Nuxt	nuxt.config.ts 的 css 数组

第 5 步：防止 FOUC

**目标：**消除无样式内容闪烁。

思考框架：

• “CSS 是渲染阻塞式还是异步加载？”
• “首次有意义绘制显示了什么？”
• “水合期间是否会发生内容位移？”

FOUC 的原因和解决方案：

原因	解决方案
CSS 异步加载	让关键 CSS 阻塞渲染
动态类	确保 SSR 包含所有所需的类
字体加载	使用带有预加载的 font-display: swap
主题切换	内联主题检测脚本

防 FOUC 模式：

<html class="no-js">
<head>
  
  <style>/* critical styles */</style>

  
  <script>
    const theme = localStorage.getItem('theme') || 'light';
    document.documentElement.classList.add(theme);
    document.documentElement.classList.remove('no-js');
  </script>

  
  <link rel="preload" href="/styles.css" as="style">
  <link rel="stylesheet" href="/styles.css">
</head>

第 6 步：性能优化

目标： 尽量减少 CSS 对性能的影响。

思考框架：

• “CSS 包有多大？”
• “有哪些 CSS 未被使用？”
• “哪些内容会阻塞渲染？”

性能检查清单：

• 正确配置 PurgeCSS/内容检测
• 未加载未使用的 Tailwind 插件
• 提取并内联关键 CSS
• 延迟加载非关键 CSS
• 优化字体（子集、预加载、swap）

包分析： 使用 --minify 构建并检查生成的 CSS 大小；在 v4 中，输出内容取决于检测到的内容，因此未使用的工具类不会被打包。

优化策略：

策略	使用时机
禁用未使用的核心插件	减小基础体积
使用更精确的内容 glob	加快构建速度，减小输出体积
提取关键 CSS	改善 FCP
延迟加载首屏以下的样式	减少初始 CSS

第 7 步：主题与设计令牌策略

目标： 设计易于维护的主题系统。

思考框架：

• “哪些内容需要自定义？”
• “如何处理暗色模式？”
• “设计系统的令牌有哪些？”

主题架构（v4）：

@theme {
  /* Color tokens */
  --color-primary: oklch(0.6 0.2 250);
  --color-secondary: oklch(0.7 0.15 180);

  /* Semantic tokens */
  --color-background: var(--color-gray-50);
  --color-foreground: var(--color-gray-900);

  /* Spacing scale */
  --spacing-page: 2rem;
}

/* Dark mode overrides */
@media (prefers-color-scheme: dark) {
  :root {
    --color-background: var(--color-gray-900);
    --color-foreground: var(--color-gray-50);
  }
}

暗色模式策略：

策略	实现方式
系统偏好	@media (prefers-color-scheme)
基于类	在 html 元素上切换 .dark
混合	系统默认值 + 用户覆盖

第 8 步：故障排除框架

目标： 系统地调试样式问题。

调试检查清单：

现象	检查项
类未生效	内容检测路径
页面导航时出现 FOUC	layout 中的 CSS 导入
水合不匹配	SSR 中的动态类
构建太慢	glob 模式的精确度
包太大	未使用的插件、内容路径

调试命令： 使用 DEBUG=tailwindcss:content 跟踪内容检测；向 CLI 传递 --verbose 以检查构建过程；确认动态类以完整形式出现在源代码中（v4 检测完整的类字符串，而不是插值片段）。

文档资源

Context7 库 ID：

• TailwindCSS v4：/websites/tailwindcss（2333 个片段）
• TailwindCSS v3：/websites/v3_tailwindcss（2691 个片段，评分：85.9）

官方文档：

• 文档：https://tailwindcss.com/docs
• 博客（发行说明）：https://tailwindcss.com/blog
• 升级指南：https://tailwindcss.com/docs/upgrade-guide

安装与工具

始终安装 tailwindcss@latest，并搭配与构建工具匹配的官方加载器—— 确保两者版本一致。

# Vite (recommended for SvelteKit / Vite apps)
npm i -D tailwindcss@latest @tailwindcss/vite@latest

# PostCSS
npm i -D tailwindcss@latest @tailwindcss/postcss@latest

# CLI
npm i -D tailwindcss@latest @tailwindcss/cli@latest

# Webpack / Next.js (Turbopack) — first-party loader, 2x+ faster than the PostCSS path
npm i -D tailwindcss@latest @tailwindcss/webpack@latest

构建工具	加载器	备注
Vite	@tailwindcss/vite	SvelteKit 的标准方案；添加到 vite.config 插件中
Webpack / Next.js	@tailwindcss/webpack	官方加载器（v4.2+）；速度快于 @tailwindcss/postcss
PostCSS	@tailwindcss/postcss	与框架无关的备用方案

TailwindCSS v4 主要变更

CSS 优先配置（v4.0）

/* v4 uses CSS @import instead of @tailwind directives */
@import "tailwindcss";

/* Design tokens as CSS variables */
@theme {
  --color-primary: oklch(0.7 0.15 200);
  --font-display: "Inter", sans-serif;
  --breakpoint-3xl: 1920px;
}

自动内容检测（v4.0）

/* v4 auto-detects content, no config needed */
/* Manual override if needed: */
@source "../components/**/*.tsx";

v4.0 核心功能

/* Container queries */
@container (min-width: 400px) {
  .card { /* styles */ }
}

/* 3D transforms */
.element {
  @apply rotate-x-45 perspective-500;
}

/* Modern color functions */
.button {
  background: oklch(0.7 0.15 200);
}

v4.0 之后的新功能（变更日志）

跟踪各个小版本的更新——该技能必须反映当前的功能集，而不只是 v4.0。

v4.1

• text-shadow-* 工具类（text-shadow-sm … text-shadow-lg，支持颜色和不透明度）。
• mask-* 工具类：mask-image、遮罩合成以及渐变遮罩 （mask-t-from-*、mask-radial-* 等）。

v4.2

• 新增调色板： mauve、olive、mist、taupe（偏中性的色阶）。
• @tailwindcss/webpack 官方加载器——速度比 PostCSS 路径快 2 倍以上 （利于 Next.js / Turbopack）。
• 扩展逻辑属性： pbs-*/pbe-*、mbs-*/mbe-*、 scroll-pbs-*/scroll-mbs-*、border-bs/border-be-*、逻辑尺寸 （block-*、inline-*、min-block-*、max-inline-*）以及逻辑内边距 （inset-s-*、inset-e-*、inset-bs-*、inset-be-*）。
• 弃用： start-* / end-* → 请改用 inset-s-* / inset-e-*。
• font-features-* 用于设置原始的 font-feature-settings（优先使用 tabular-nums 等高级工具类）。

v4.3

• 滚动条工具类： scrollbar-auto / scrollbar-thin / scrollbar-none （scrollbar-width）；scrollbar-thumb-* / scrollbar-track-*（scrollbar-color， 支持 /opacity）；scrollbar-gutter-auto / -stable / -both。
• @container-size： 创建一个 size 容器，提供块轴查询单位 （cqb/cqh）；而 @container 只会创建内联尺寸容器； 可通过 @container-size/{name} 命名。
• zoom-* 工具类（zoom-75/-100/-125、任意值 zoom-[1.1]、zoom-(--var)）。
• tab-* 工具类，用于设置 tab-size（tab-2/tab-8、任意值、变量）。
• CSS 中的堆叠式与复合 @variant： @variant hover:focus {} 和 @variant hover, focus {}。
• 通过 --value(…)/--modifier(…) 内的 --default(…) 为功能型工具类设置默认值：

  @utility tab-* {
    tab-size: --value(integer, --default(4)); /* bare `tab` now works */
  }
  

SSR 性能检查清单

关键 CSS

• 内联首屏可见区域的 CSS
• 延迟加载非关键样式表
• 使用 <link rel="preload"> 加载字体

水合

• 避免水合期间发生布局偏移
• 确保服务端与客户端生成的类名一致
• 在禁用 JavaScript 的情况下测试

防止 FOUC

<html class="no-js">
<head>
  <script>document.documentElement.classList.remove('no-js')</script>
  <style>.no-js .lazy-load { visibility: hidden; }</style>
</head>

框架集成

SvelteKit

推荐路径：添加 @tailwindcss/vite 插件，然后在 app.css 中 @import "tailwindcss"，并在根布局中导入一次。

// vite.config.ts
import { sveltekit } from '@sveltejs/kit/vite';
import tailwindcss from '@tailwindcss/vite';
import { defineConfig } from 'vite';

export default defineConfig({ plugins: [tailwindcss(), sveltekit()] });

<script>
  import '../app.css';
</script>

/* app.css */
@import "tailwindcss";

Next.js

// app/layout.tsx
import './globals.css';

/* globals.css */
@import "tailwindcss";

性能优化

PurgeCSS（生产环境）

/* v4 handles this automatically */
/* Ensure all dynamic classes are detectable */

自定义变体

@variant hocus (&:hover, &:focus);
@variant group-hocus (:merge(.group):hover &, :merge(.group):focus &);

减小打包体积

/* Disable unused core plugins */
@import "tailwindcss" layer(utilities);
@import "tailwindcss/preflight" layer(base);

使用理念

• 组件优先于 CSS 抽象。 优先使用由工具类设置样式的真实、可复用组件， 而不是在 CSS 中通过 @variant/@apply 隐藏工具类。
• 优先使用高级工具类，再考虑变通方案。 优先使用 tabular-nums、 逻辑属性 inset-s-*、滚动条和容器工具类，再考虑任意值或原始的 font-features-*。
• 默认采用 CSS 优先配置。 通过 @theme 令牌设置主题；让 v4 自动检测内容。
• 默认使用逻辑属性，以支持国际化和 RTL 布局 （inset-s-*/pbs-*），而非已弃用的 start-*/end-*。

浏览器兼容性

TailwindCSS v4 面向现代浏览器基线（请对照升级指南确认当前最低版本要求；并注意 mask-*/scrollbar-color 等较新的工具类可能有更严格的单项特性支持要求）：

• Safari 16.4+
• Chrome 111+
• Firefox 128+
• Edge 111+

向用户展示结果

提供 TailwindCSS 解决方案时：

• 说明 v3 与 v4 的语法差异
• 提供可直接复制粘贴的配置
• 考虑 SSR 框架的特定集成方式
• 说明浏览器兼容性要求
• 包含性能影响

故障排除

“样式未生效”

• 检查内容检测路径
• 确认 CSS 导入正确
• 清除构建缓存

“FOUC（无样式内容闪烁）”

• 内联关键 CSS
• 添加适当的预加载提示
• 检查水合时机

“构建太慢”

• 缩小内容 glob 模式的范围
• 使用特定文件扩展名
• 在构建工具中启用缓存