Tailwind v3+ 构建失败主因是未传 --content 参数、残留 TAILWIND_MODE 环境变量、CI 工作目录错误、绕过框架插件链及配置文件路径误读。
构建命令里没传 --content 参数导致 PurgeCSS 扫不到文件
很多项目用自定义脚本调用 tailwindcss CLI，但忘了显式传入 --content。Tailwind v3+ 不再读 purge 字段，也不自动推导路径——你命令里不写，它就只扫描默认的 ./src/**/*.{html,js,ts,jsx,tsx}，漏掉你实际放组件的目录。
常见错误写法：npx tailwindcss -i ./src/input.css -o ./dist/output.css --minify（缺 --content）
正确做法是把 tailwind.config.js 里 content 数组的内容，原样塞进命令：
- 如果 config 里是
['./pages/**/*.{js,ts}', './components/**/*.{js,ts}']，命令就得写成：npx tailwindcss -i ./src/input.css -o ./dist/output.css --minify --content "./pages/**/*.{js,ts}" --content "./components/**/*.{js,ts}" - 路径含空格或特殊字符时，每个
--content值必须单独用双引号包裹 - 不要合并成一个字符串，比如
--content "./pages/**/*.{js,ts} ./components/**/*.{js,ts}"会失效
构建脚本用了 TAILWIND_MODE=build 却没关 JIT 的热重载逻辑
某些旧版脚本或 CI 配置里还残留 TAILWIND_MODE=build，这会强制 Tailwind 进入“构建模式”，但它在 v3.3+ 已被弃用。更麻烦的是，它可能干扰 JIT 引擎对动态 class 的识别逻辑，尤其在 Webpack/Vite 插件链里。
立即学习“前端免费学习笔记（深入）”；
真正该做的是确保环境变量干净：
- 删掉所有
TAILWIND_MODE=*的设置（包括package.json脚本、.env、CI 环境变量） - 用
TAILWIND_DISABLE_TOUCH=true替代（仅当需要跳过文件监听时） - 检查
tailwind.config.js是否有mode: 'jit'—— v3.3+ 不再支持该配置项，留着反而报错
CI/CD 构建时工作目录不对，--content glob 匹配失败
本地跑得通，CI 上样式全丢？大概率是构建命令执行时 pwd 不是项目根目录，导致 ./src/**/* 这类相对路径根本找不到文件。
验证方式：在 CI 脚本开头加一行 pwd && ls -la ./src，看输出是否真有你期望的文件结构。
修复建议：
- 改用绝对路径：比如
--content "$PWD/src/**/*.{js,ts,jsx,tsx}"（Bash）或--content "%cd%\src\**\*.{js,ts,jsx,tsx}"（Windows CMD） - 或先
cd到项目根再执行命令，别依赖相对路径 - 避免用
npm run build封装多层脚本——每层都可能改变 cwd，直接暴露 CLI 命令更可控
构建命令绕过了 Vite/Next.js 的插件链，没触发 PostCSS 处理
有些团队为“提速”直接调用 tailwindcss CLI，跳过 Vite 或 Next.js 的构建流程。问题在于：Tailwind 的 @tailwind 指令必须经 PostCSS 解析，而 CLI 默认不加载 postcss.config.js 里的插件（比如 autoprefixer），会导致生成的 CSS 缺少浏览器前缀，甚至部分变体类（如 dark:、hover:）未展开。
除非你明确知道在做什么，否则别手写 CLI 命令：
- 用框架原生命令：Vite 项目用
vite build，Next.js 用next build，它们内部已集成 Tailwind 插件 - 若必须用 CLI 测试，加
--postcss标志，并确认postcss.config.js存在且启用tailwindcss插件 - 检查输出 CSS 文件头部是否有
/* purgecss start ignore */类注释——有说明 PostCSS 链生效了
最常被忽略的一点：构建命令是否真的在读你改过的 tailwind.config.js？CLI 默认找当前目录下的配置，但如果命令从子目录执行，它可能读到 node_modules 里的默认配置。先 ls -la tailwind.config.js 确认路径，再动手改命令。
