47. v3 到 v4 迁移指南（二）：配置迁移

上一节了解了 v3 到 v4 的核心差异，这节重点是实际操作——如何把项目从 v3 迁移到 v4。

使用迁移工具

官方提供了自动迁移工具，能处理大部分机械性工作：

npx @tailwindcss/upgrade

迁移工具会：

1. 更新依赖（package.json）
2. 将 tailwind.config.js 中的配置转换为 CSS
3. 更新模板文件中的类名（如废弃工具类、重命名工具类）
4. 迁移 PostCSS 配置

迁移前的准备

# 1. 确保 Node.js 版本 >= 20
node --version

# 2. 在新分支上操作
git checkout -b upgrade/tailwind-v4

# 3. 备份重要文件
cp tailwind.config.js tailwind.config.js.bak

运行迁移工具

npx @tailwindcss/upgrade

迁移后检查

# 1. 查看变更
git diff

# 2. 在浏览器中测试
npm run dev

# 3. 检查关键页面和功能

手动迁移步骤

如果迁移工具无法完全处理，或者你想更精细地控制迁移过程，可以按以下步骤手动迁移。

步骤 1：更新依赖

# 卸载 v3 依赖
npm uninstall tailwindcss postcss autoprefixer

# 安装 v4 依赖（选择适合你的方式）
# Vite 项目
npm install tailwindcss @tailwindcss/vite

# PostCSS 项目
npm install tailwindcss @tailwindcss/postcss

# CLI 项目
npm install tailwindcss @tailwindcss/cli

步骤 2：更新入口 CSS

/* v3 的入口文件 */
@tailwind base;
@tailwind components;
@tailwind utilities;

/* 改为 v4 */
@import "tailwindcss";

步骤 3：迁移主题配置

// v3: tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: {
        brand: '#3b82f6',
      },
      fontFamily: {
        display: ['Satoshi', 'sans-serif'],
      },
      spacing: {
        '18': '4.5rem',
      },
    },
  },
}

/* v4: app.css */
@import "tailwindcss";

@theme {
  --color-brand: oklch(0.62 0.21 259.815);
  --font-display: "Satoshi", sans-serif;
  --spacing-18: 4.5rem;
}

步骤 4：更新 PostCSS 配置（如适用）

// v3: postcss.config.mjs
export default {
  plugins: {
    'postcss-import': {},
    tailwindcss: {},
    autoprefixer: {},
  },
}

// v4: postcss.config.mjs
export default {
  plugins: {
    '@tailwindcss/postcss': {},
  },
}

或者直接使用 Vite 插件（推荐）：

// vite.config.ts
import { defineConfig } from "vite";
import tailwindcss from "@tailwindcss/vite";

export default defineConfig({
  plugins: [tailwindcss()],
});

步骤 5：更新模板中的类名

搜索并替换废弃的工具类：

bg-opacity-*    → bg-*/50
text-opacity-*  → text-*/50
border-opacity-* → border-*/50
flex-shrink-*   → shrink-*
flex-grow-*     → grow-*
overflow-ellipsis → text-ellipsis
outline-none    → outline-hidden
ring            → ring-3

步骤 6：测试和修复

运行项目，逐个页面检查样式是否正确：

npm run dev

常见迁移场景

场景 1：保留 v3 配置

如果不想立即重写配置，可以用 @config 指令暂时保留：

@import "tailwindcss";
@config "../../tailwind.config.js";

场景 2：迁移自定义插件

// v3: tailwind.config.js
module.exports = {
  plugins: [
    function({ addUtilities }) {
      addUtilities({
        '.scrollbar-hidden': {
          'scrollbar-width': 'none',
        },
      });
    },
  ],
}

/* v4 */
@utility scrollbar-hidden {
  scrollbar-width: none;
}

场景 3：迁移动态类名

// v3/v4 都需要避免这种写法
const color = 'red';
<div className={`text-${color}-500`}>不会生效</div>

// 改为完整类名映射
const colorMap = {
  red: 'text-red-500',
  blue: 'text-blue-500',
};
<div className={colorMap[color]}>会生效</div>

场景 4：迁移安全列表

// v3: tailwind.config.js
module.exports = {
  safelist: [
    'bg-red-500',
    'text-3xl',
    'lg:text-4xl',
  ],
}

/* v4 */
@source inline("bg-red-500");
@source inline("text-3xl");
@source inline("lg:text-4xl");

场景 5：迁移容器配置

// v3: tailwind.config.js
module.exports = {
  theme: {
    container: {
      center: true,
      padding: '2rem',
    },
  },
}

/* v4 */
@utility container {
  margin-inline: auto;
  padding-inline: 2rem;
}

场景 6：迁移暗色模式

// v3: tailwind.config.js
module.exports = {
  darkMode: ['class', '.dark'],
}

/* v4 */
@custom-variant dark (&:where(.dark, .dark *));

迁移检查清单

迁移完成后，逐项检查：

• 所有页面样式正常
• 响应式布局正常
• 暗色模式正常（如有）
• 自定义组件样式正常
• 表单元素样式正常
• 动画和过渡效果正常
• 第三方库样式未被破坏
• 构建产物大小合理
• 开发环境热更新正常

回滚计划

如果迁移遇到无法解决的问题，准备好回滚：

# 放弃当前更改
git checkout .
git checkout main

# 或回滚到迁移前
git reset --head HEAD@{1}

迁移是个过程，不是一次性操作。理解差异、用好工具、逐步验证，才能让迁移平稳完成。