11. v4 版本升级指南

11. v4 版本升级指南1. 概述Tailwind CSS v4 是一个重大版本更新从 JavaScript 配置转向 CSS 优先的配置方式。1.1 主要变化变化v3v4配置方式tailwind.config.jsCSS 文件 (theme)安装方式postcsstailwindcsstailwindcss/vite等暗色模式dark:前缀相同但配置方式变化自定义主题theme.extendtheme块插件plugins数组plugin指令2. 升级前的准备2.1 检查当前版本tailwindcss--version2.2 备份项目# 提交当前代码gitadd.gitcommit-m备份升级 Tailwind v4 前2.3 查看破坏性变更官方升级指南注意项目中使用的自定义配置3. 升级步骤3.1 卸载旧版本npmuninstall tailwindcss postcss autoprefixer3.2 安装 v4# 根据项目类型选择npminstalltailwindcss/vite# Vite 项目npminstalltailwindcss/cli# CLI 项目npminstalltailwindcss/postcss# PostCSS 项目3.3 更新配置文件Vite 项目// vite.config.jsimport{defineConfig}fromviteimportreactfromvitejs/plugin-reactimporttailwindcssfromtailwindcss/viteexportdefaultdefineConfig({plugins:[react(),tailwindcss(),],})PostCSS 项目// postcss.config.jsmodule.exports{plugins:{tailwindcss/postcss:{},},}3.4 更新 CSS 文件/* 之前 (v3) */tailwindbase;tailwindcomponents;tailwindutilities;/* 之后 (v4) */importtailwindcss;3.5 迁移配置颜色配置/* v3: tailwind.config.js */module.exports {theme:{extend:{colors:{brand:#6366f1,},},},}/* v4: src/index.css */importtailwindcss;theme{--color-brand:#6366f1;--color-brand-light:#818cf8;--color-brand-dark:#4f46e5;}字体配置/* v3 */theme:{extend:{fontFamily:{sans:[Inter,system-ui],},},}/* v4 */theme{--font-sans:Inter,system-ui,sans-serif;}断点配置/* v3 */theme:{extend:{screens:{3xl:1920px,},},}/* v4 */theme{--breakpoint-3xl:1920px;}间距配置/* v3 */theme:{extend:{spacing:{18:4.5rem,},},}/* v4 */theme{--spacing-18:4.5rem;}3.6 迁移插件/* v3: tailwind.config.js */module.exports {plugins:[require(tailwindcss/typography),require(tailwindcss/forms),],}/* v4: src/index.css */importtailwindcss;plugintailwindcss/typography;plugintailwindcss/forms;3.7 迁移自定义插件/* v3: plugins/custom.js */constpluginrequire(tailwindcss/plugin);module.exportsplugin(function({addUtilities}){addUtilities({.text-gradient:{background:linear-gradient(135deg, #6366f1, #a855f7),-webkit-background-clip:text,background-clip:text,color:transparent,},});});/* v4: src/index.css */importtailwindcss;utilitytext-gradient{background:linear-gradient(135deg,#6366f1,#a855f7);-webkit-background-clip:text;background-clip:text;color:transparent;}4. 常见迁移问题4.1 类名不生效问题升级后某些类名不生效原因动态拼接的类名可能未被识别解决// ❌ 不生效 div className{text-${color}-500} // ✅ 使用完整类名或映射 const colors { red: text-red-500, blue: text-blue-500, }; div className{colors[color]}4.2 自定义主题不生效问题theme中的配置不生效原因语法错误或位置错误解决/* ✅ 正确位置在 import 之后 */importtailwindcss;theme{--color-brand:#6366f1;}/* ❌ 错误在 import 之前 */theme{--color-brand:#6366f1;}importtailwindcss;4.3 插件不兼容问题某些第三方插件还不支持 v4解决检查插件是否发布 v4 兼容版本临时用utility替代等待插件更新4.4 PostCSS 配置问题问题postcss.config.js格式变化解决// v3module.exports{plugins:{tailwindcss:{},autoprefixer:{},},}// v4module.exports{plugins:{tailwindcss/postcss:{},},}5. 新特性使用5.1 容器查询importtailwindcss;plugintailwindcss/container-queries;divclasscontainerdivclassgrid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3!-- 根据容器宽度响应 --/div/div5.2 3D 变换importtailwindcss;plugintailwindcss-3d;divclasspreserve-3d rotate-x-45 rotate-y-303D 元素/div5.3 自定义变体custom-variantchildren( *);/* 使用 */div classchildren:mb-2 div每个子元素都有下边距/div div每个子元素都有下边距/div /div6. 升级检查清单升级前备份项目代码记录自定义配置记录使用的插件检查是否有动态类名升级中卸载旧版本安装新版本更新构建配置更新 CSS 文件迁移主题配置迁移插件配置升级后运行开发服务器检查样式是否正常检查暗色模式检查响应式布局检查自定义类运行生产构建7. 完整迁移示例7.1 迁移前 (v3)// tailwind.config.jsmodule.exports{content:[./src/**/*.{html,js}],darkMode:class,theme:{extend:{colors:{brand:#6366f1,},fontFamily:{sans:[Inter,system-ui],},},},plugins:[require(tailwindcss/typography),],}/* src/index.css */tailwindbase;tailwindcomponents;tailwindutilities;.btn-primary{applypx-4 py-2 bg-brand text-white roundedhover:bg-brand-dark;}7.2 迁移后 (v4)/* src/index.css */importtailwindcss;plugintailwindcss/typography;theme{--color-brand:#6366f1;--color-brand-dark:#4f46e5;--font-sans:Inter,system-ui,sans-serif;}.btn-primary{applypx-4 py-2 bg-brand text-white roundedhover:bg-brand-dark;}// vite.config.jsimport{defineConfig}fromviteimporttailwindcssfromtailwindcss/viteexportdefaultdefineConfig({plugins:[tailwindcss()],})8. 练习练习 1迁移配置将下面的 v3 配置迁移到 v4// tailwind.config.jsmodule.exports{theme:{extend:{colors:{primary:#3b82f6,secondary:#8b5cf6,},screens:{xs:480px,},},},plugins:[require(tailwindcss/forms),],}参考答案importtailwindcss;plugintailwindcss/forms;theme{--color-primary:#3b82f6;--color-secondary:#8b5cf6;--breakpoint-xs:480px;}9. 总结对比项v3v4配置位置tailwind.config.jsCSS 文件主题配置theme.extendtheme块插件配置plugins数组plugin指令自定义类JavaScript 插件utility指令变体JavaScript 插件custom-variant一句话总结Tailwind v4 从 JavaScript 配置转向 CSS 优先配置更直观性能更好但需要按升级指南迁移现有项目。