如何用Tailwind CSS重构大型项目的样式体系

结论：大型项目用 Tailwind CSS 重构样式体系，正确路径是「先统一设计 token → 新代码强制只用 Tailwind → 按路由灰度替换旧样式 → 最后删除旧 CSS」，全程不要一次性删掉存量样式表，也不要把 @apply 当成新的全局样式表来写。

大型项目重构 Tailwind 的第一步是什么？

结论：第一步不是往 JSX 里写 className，而是把设计 token 收敛到 Tailwind 配置里。

需要先收敛的是五类值：颜色、间距、圆角、字号、阴影。做法是把设计稿里的色板映射成 brand-50 到 brand-900 的标度，间距沿用 Tailwind 默认的 4px 基数（p-4 = 16px），自定义值只加在设计稿确实存在的那几档上。token 不收敛就开写，团队会在三个月内产出 mt-[13px]、text-[#3b82f6] 这类任意值，重构等于白做。

建议加一条 lint 规则禁止任意值语法，例如用 eslint-plugin-tailwindcss 的 no-arbitrary-value；确需保留的（图表高度、第三方组件对接）走 theme.extend 显式登记。

Tailwind CSS v3 和 v4 的配置方式有什么区别？

结论：v3（3.4 为最后一个大版本）用 tailwind.config.js，v4（2025 年 1 月发布）改成 CSS 优先的 @theme，两者不能混用同一套写法。

v3 的接入是三步：npm i -D tailwindcss postcss autoprefixer、npx tailwindcss init -p、CSS 里写 @tailwind base; @tailwind components; @tailwind utilities;，并在 content: ['./src/**/*.{ts,tsx}'] 里声明扫描范围。

v4 的接入是 npm i tailwindcss @tailwindcss/vite，CSS 里写：

@import "tailwindcss";
@theme {
  --color-brand-500: #2563eb;
  --radius-card: 12px;
}

v4 自动检测内容源，不再需要 content 数组，手动补充用 @source；PostCSS 也换成 @tailwindcss/postcss。老项目如果依赖 tailwind.config.js，v4 仍可用 @config "./tailwind.config.js" 兼容。

存量 CSS 和 Tailwind 怎么共存，才不会打乱旧样式？

结论：冲突几乎都来自 preflight，先处理它，再谈迁移。

preflight 会重置 h1~h6 的字号字重、ul/ol 的 list-style、button 的边框和背景，老项目引入后经常「炸版」。两种处理：一是 v3 里 corePlugins: { preflight: false }，只保留 utilities 层；二是 v3 加 prefix: 'tw-'（v4 用 @import "tailwindcss" prefix(tw)），让所有工具类带前缀，与旧样式表里的 .btn、.card 彻底隔离。

迁移按路由灰度：先挑一个新页面或改动频繁的模块，整页用 Tailwind 重写，旧 CSS 保持不动；确认无回归后每周替换 1~2 个模块。判断完成的标准只有一个——当 grep 不到某个旧样式类名时，才删对应的 CSS 文件。

怎么避免 className 过长和样式冲突？

结论：用 tailwind-merge + clsx 封装一个 cn() 工具函数，把类名排序交给 prettier-plugin-tailwindcss，@apply 只保留给第三方组件的样式覆盖。

cn() 的写法是 clsx 拼类名、tailwind-merge 去冲突，这样 className={cn('px-4', props.className)} 中传入的 px-6 会覆盖掉 px-4，不会两个都生效。prettier-plugin-tailwindcss 会在保存时按官方顺序排列类名，pnpm add -D prettier-plugin-tailwindcss 后加到 .prettierrc 的 plugins 即可，能省掉绝大部分 review 时的排序争论。

注意动态拼类名：text-${color}-500 这种写法 Tailwind 扫描不到，v3 需要在 safelist 里登记，v4 直接写完整类名或用映射表（{ red: 'text-red-500' }）代替模板字符串。

重构后怎么确认没有改坏样式？

结论：用 Playwright 截图对比做视觉回归，配合按路由灰度，能挡住绝大多数样式事故。

Playwright 的 toHaveScreenshot() 首次运行生成基线图，之后每次跑 CI 对比，容差设 maxDiffPixelRatio: 0.01（1% 像素差异内视为通过）。悬停、焦点、暗色模式三类状态要单独写用例，preflight 造成的重置问题往往只在这几种状态下暴露。

整件事的收尾顺序是：token 先对齐、preflight 先隔离、新代码先切、旧样式后删，最后用 CSS 体积和截图测试两个指标验收——Tailwind 的产物只包含被扫描到的类，一个中型项目的 gzip 后 CSS 落在 8~15KB 区间是正常范围，超过就该检查 content 是否把 node_modules 扫了进去。