升级前必须确认三件事：是否使用vite/webpack/standalone模式、是否备份tailwind.config.js及自定义CSS文件、目标环境是否支持现代CSS特性（如安卓WebView需Chrome99+），否则升级将失败。
升级前必须确认的三件事
别急着跑命令，先看这三项是否满足，否则后续全白干：
- 项目是否使用
vite、webpack或standalone（Django Tailwind）？不同构建方式升级路径完全不同 - 是否已备份
tailwind.config.js和所有自定义 CSS 文件？v4 会彻底废弃该配置文件的旧写法 - 目标浏览器/运行环境是否支持现代 CSS 特性？特别是安卓 WebView 低于 Chrome 99 的设备会直接丢弃全部样式（因 v4 强依赖
@layer）
npm/vite 项目：重装 CLI + 替换 import 语句
v3 的 postcss 插件链和 @tailwind 指令在 v4 中已被移除，必须切换为原生 @import 方式。
- 卸载旧依赖：
yarn remove tailwindcss postcss autoprefixer（若用 npm 则用npm uninstall） - 安装新工具链：
yarn add -D tailwindcss @tailwindcss/vite - 替换 CSS 入口文件（如
src/index.css）内容为仅一行：@import "tailwindcss";—— 不再需要@tailwind base/components/utilities - 更新
vite.config.ts，确保插件已注册：plugins: [react(), tailwindcss()]
注意：@config 指令在 v4 中无效，所有配置必须通过 @theme 块或 CSS 变量声明，tailwind.config.js 文件可删除。
颜色与暗色模式：必须改写，不能沿用 v3 写法
v3 中写在 tailwind.config.js 里的 colors 和 darkMode: 'class' 在 v4 中完全失效。
立即学习“前端免费学习笔记（深入）”；
- 自定义颜色必须转为 CSS 变量，并包裹在
@theme块中，例如：@theme { --color-primary-500: #3b82f6; } - 暗色模式不再识别
dark:前缀类，需手动定义@custom-variant，例如：@custom-variant dark (&:where(.dark, .dark *)); - HTML 根元素仍需加
class="dark"，但 class 名本身无意义，起作用的是上面定义的@custom-variant
漏掉这两项，所有 bg-primary-500、dark:bg-gray-800 都不会生效，且控制台不报错 —— 这是最容易被忽略的静默失败点。
Django Tailwind standalone 模式：只改版本号，不碰 npm
如果你用的是 Django Tailwind 的 --tailwind-version 4s 初始化方式，整个升级过程只涉及三步，且与前端构建无关：
- 修改
settings.py中的TAILWIND_STANDALONE_BINARY_VERSION，设为最新版，例如："v4.2.0" - 执行：
python manage.py tailwind install（自动下载新二进制） - 重建 CSS：
python manage.py tailwind build
注意：check-updates 和 update 命令对 standalone 模式无效；package.json 里不需要也不应该有 tailwindcss 依赖 —— 它由二进制独立提供。
v4 的核心不是“多加几个类”，而是整套 CSS 处理模型的重构。最常卡住的地方不是命令跑不通，而是旧配置残留+现代 CSS 特性兼容性没兜底。尤其当项目要支持老安卓 WebView 时，得提前验证 @layer 是否可用，而不是等上线才发现页面变白板。
