Tailwind v4 首屏慢主因是 content 字段漏配导致类被误删，非框架本身重；需显式覆盖所有路径（含 App Router 的 layout/loading、MDX 文件），禁用未用插件与变体，避免动态 class 字符串，构建必须用 --minify 和 TAILWIND_MODE=build。
tailwind.config.js 的 content 字段必须全覆盖且显式声明
首屏渲染慢，80% 的情况不是 Tailwind 本身重，而是它“猜错了”哪些类该保留。v4 的 JIT 引擎只扫描 content 字段里列出的路径里的字面量 class 名，漏掉一个文件，dark:bg-gray-900 或 md:grid-cols-2 就可能直接消失。
常见错误现象：本地开发一切正常，构建后按钮没 hover 效果、暗色模式不生效、响应式布局塌陷——基本都是 content 漏配。
- Next.js App Router 必须同时包含：
./app/**/*.{js,ts,jsx,tsx}和./src/components/**/*.{js,ts,jsx,tsx}；漏掉layout.tsx或loading.tsx，dark:变体大概率失效 - 用了
.mdx（如文档页），必须显式加：./src/**/*.mdx；否则里面写的text-blue-500被当成死代码裁掉 - 避免写
./**/*.tsx：某些 Node 版本下 glob 失效，推荐分层列明：./app/**/*.{js,ts,jsx,tsx}、./components/**/*.{js,ts,jsx,tsx}
动态 class 名必须兜底，不能靠 safelist 硬塞
v4 的 PurgeCSS 机制对模板字符串完全无感：className={`p-${size}` 或 class={\`text-\${color}-600\`} 在构建时会被跳过，导致首屏 padding 丢失、文字变黑——但你根本不会在本地发现。
性能影响很隐蔽：硬加 safelist: ['p-2', 'p-4', 'p-6'] 看似解决问题，实则让所有尺寸类全量注入，CSS 体积翻倍，Lighthouse “消除渲染阻塞资源”评分直接崩到 30 分以下。
立即学习“前端免费学习笔记（深入）”；
- 优先改用
@apply封装成确定类名，写在@layer components或.module.css里 - 若必须动态控制（如画板工具栏的笔刷粗细），用 CSS 变量 +
style替代：style={{ padding: sizeMap[size] }} - 极少数需保留动态类的场景，用
/* @preserve */注释标记，而非全局 safelist
禁用未用插件 + 精简变体，v4 的配置更轻但更敏感
v4 默认启用的插件（如 @tailwindcss/aspect-ratio、@tailwindcss/container-queries）和变体（如 group-hover、focus-within）若项目首屏完全不用，会生成大量冗余 CSS，直接污染关键渲染路径。
移动端尤其明显：首屏几乎只用 sm: 断点，但若未在 theme.screens 中显式限制，xl:text-4xl 这类类仍会被生成并打包进 output.css。
- 检查插件必要性：
@tailwindcss/forms和@tailwindcss/typography按需引入，首屏无富文本或表单可全禁 - 变体只开真正用到的：
variants: { extend: { backgroundColor: ['hover', 'focus'] } }，别留['responsive', 'hover', 'focus', 'active', 'group-hover']全集 - 自定义断点时保持步长合理：
'sm': '640px'、'md': '768px'、'lg': '1024px'，避免'xs': '320px'+'xxs': '240px'这种过度细分
构建命令必须走生产模式且带 --minify
v4 的裁剪逻辑只在生产构建阶段触发。开发时 npm run dev 是内存中实时生成，完全不反映真实体积；你以为 14KB 的 CSS，上线后可能是 320KB。
错误写法：npx tailwindcss -i ./src/input.css -o ./dist/output.css —— 缺 --minify，也未设 TAILWIND_MODE=build，Purge 完全不执行。
- 正确命令：
TAILWIND_MODE=build npx tailwindcss -i ./src/input.css -o ./dist/output.css --minify - Next.js 用户务必确认
next build调用的是 v4+ 的 PostCSS 插件（@tailwindcss/postcss），旧版 CLI 插件即使配了content也不会裁剪 - 验证是否真生效：不要看输出文件大小，用浏览器 DevTools → Network → 查看实际注入首屏的 CSS 字节数，或运行
npx tailwindcss analyze对比前后未用类数量
最易被忽略的一点：v4 的 CSS 变量支持虽强，但如果你在 :root 里手动写了大量 --tw-bg-opacity 类变量，又没配合 optimizeUniversalDefaults，反而会拖慢解析。真正的性能提升，永远来自精准控制“哪些类存在”，而不是“怎么写变量”。
