Tailwind CSS 按需构建的核心是 content 配置必须精准匹配所有含类名的源码路径，否则生产构建会删除未扫描到的类导致白屏；需显式列出文件扩展名、包含 HTML 文件、区分 Vite 与 PostCSS 模式，并避免动态 class 拼接，safe-list 仅作兜底。
按需构建 Tailwind CSS 的核心是让 content 配置精准匹配源码路径，否则生产构建时会删掉所有用到的类——不是“没生效”，而是根本没打进 CSS 文件里。
content 路径写错导致生产环境白屏或无样式
这是最常见也最隐蔽的问题：开发时一切正常（因为 Vite 或 Webpack dev server 会全量注入），但 npm run build 后页面变成纯 HTML 结构，没有颜色、间距、响应式断点等任何 Tailwind 类效果。
-
content必须显式列出所有可能含 Tailwind 类名的文件路径，不能靠 glob 通配符“猜”——比如"./src/**/*"不够，得写成"./src/**/*.{js,jsx,ts,tsx}" - 如果用了
public/index.html且在里面写了className（比如 SSR 或静态 landing page），必须加进content数组，否则 HTML 中的类也会被 purge - Vite 插件模式下（
@tailwindcss/vite），content是插件自己扫描的依据，和 PostCSS 无关；而传统 PostCSS 模式下，它由tailwindcss自己读取，但路径语义一致
create-react-app 项目不能用 @tailwindcss/vite
如果你的项目是 npx create-react-app 创建的，或者基于 Webpack（如 Next.js 13 之前、Gatsby），@tailwindcss/vite 插件完全不生效——它只认纯 Vite 构建流程。
- 这种项目必须走 PostCSS 流程：安装
tailwindcss+postcss+autoprefixer，并配置postcss.config.js -
tailwind.config.js中的content字段仍需精确，否则 build 后照样丢样式 - 不要尝试在
webpack.config.js里手动加@tailwindcss/vite——它不是 PostCSS 插件，Webpack 加了也没用，还会报错
class 名动态拼接导致未被识别
Tailwind 的 purging 是静态分析，无法解析运行时拼接的字符串。下面这些写法会让对应类名在构建时被删掉：
构建 Shopify 嵌入式应用（Embedded App）的开发技能：基于 @shopify/shopify-app-react-router + React Router v7 + Admin API 2026-04。覆盖 shopifyApp 配置、authenticate.admin 的 GraphQL/REST 调用、Webhook 校验、Session 存储、订阅计费、App Bridge 导航、部署，并新增：适用场景判断、安全最佳实践、错误处理与容错、最佳实践、常见问题 FAQ、高级场景。G
立即学习“前端免费学习笔记（深入）”；
-
className={`text-${color}-500`}→color是变量，插件扫不到完整类名 -
className={isActive ? 'bg-blue-500' : 'bg-gray-200'}→ 两种类名都得出现在源码中（实际已出现，安全） -
className={clsx('p-4', isPrimary && 'bg-blue-500')}→clsx是函数调用，插件通常能识别，但复杂嵌套或自定义工具函数可能失效
解决办法：把可能用到的类名在任意 JSX 中“显式写出”一次（哪怕注释里），或改用 safe-list 配置（见下条）。
safe-list 是兜底方案，不是替代 content 的捷径
safe-list 可以强制保留某些类名，但它不解决根本问题——只是绕过扫描逻辑。滥用会导致打包体积膨胀、失去按需构建意义。
- 适合场景：动态生成的类（如
bg-[#1da1f2]）、CSS-in-JS 插值、第三方组件库注入的 Tailwind 类 - 配置示例：
safeList: [/^bg-/, /^text-/, /^p-/]→ 会保留所有以这些前缀开头的类，但也会带上你根本没用过的bg-amber-900等 - 真正该优先做的，还是检查
content是否覆盖全部 JSX/TSX/HTML 文件，以及是否遗漏了服务端渲染模板或 MDX 文件
最关键的细节往往藏在 content 数组里——它不是“配置项之一”，而是按需构建的开关本身。路径差一个字符，build 就等于没配 Tailwind。
