升级指南

Tailwind CSS v2.0 是自2019年5月发布 v1.0 以来的第一个新的主要版本，因此它包括一些小的不兼容性变更。

我们不会轻易作出不兼容性的变更，并努力确保升级路径尽可能简单。对于大多数项目来说，升级应该在30分钟内完成。

如果您的项目使用 @tailwindcss/ui 插件，请务必阅读 Tailwind UI for Tailwind CSS v2.0 升级指南。

安装 Tailwind CSS v2.0 和 PostCSS 8

Tailwind CSS v2.0 已经更新为最新的 PostCSS 版本，这需要安装 postcss 和 autoprefixer 作为其依赖，同时安装 Tailwind 本身。

更新 Tailwind 并使用 npm 安装 PostCSS 和 autoprefixer。

npm install tailwindcss@latest postcss@latest autoprefixer@latest

如果您遇到问题，您可能需要使用我们的 PostCSS 7兼容性版本。

已取消对IE 11 的支持

在v2.0之前，我们尽力确保我们在 Tailwind 中包含的功能尽可能在 IE 11 中工作。这增加了相当大的维护负担，以及增加了构建的大小（即使在清理未使用的样式），所以我们决定从v2.0开始放弃对IE 11的支持。

如果您需要支持 IE 11，我们建议继续使用 Tailwind CSS v1.9，直到您不再需要支持 IE。

升级到Node.js 12.13或更高版本

Tailwind CSS v2.0 不再支持 Node.js 8或10。要建立您的 CSS，您需要确保您在本地和 CI 环境中运行 Node.js 12.13.0或更高版本。

更新排版和表单插件

如果您正在使用 @tailwindcss/typography，您需要升级到 v0.3.0，它增加了 Tailwind CSS v2.0 的支持。

如果您正在使用 @tailwindcss/custom-forms，您将需要迁移到 @tailwindcss/forms 来取代它。请在发布说明中了解更多关于新表单插件的信息。

@tailwindcss/custom-forms 插件与 Tailwind CSS v2.0不兼容。

删除未来和实验性的配置选项

从 v2.0 开始，就没有 future 或 experimental 选项了，所以您可以从您的 tailwind.config.js 文件中删除任何这样的配置。

  module.exports = {
-   future: {
-     defaultLineHeights: true,
-     purgeLayersByDefault: true,
-     removeDeprecatedGapUtilities: true,
-   },
-   experimental: {
-       additionalBreakpoint: true,
-       extendedFontSizeScale: true,
-       extendedSpacingScale: true,
-   },
    // ...
  }

未来我们会继续使用 experimental 选项来实现新的功能想法，但 future 可能不会使用该选项。

更新重命名的功能类

在 v2.0 中，有一小部分功能类被重新命名。

旧名	新名
`whitespace-no-wrap`	`whitespace-nowrap`
`flex-no-wrap`	`flex-nowrap`
`col-gap-{n}`	`gap-x-{n}`
`row-gap-{n}`	`gap-y-{n}`

您应该能够在整个项目中非常安全地全局查找和替换这些类，因为它们是非常不同的字符串。

更新 whitespace-no-wrap 和 flex-no-wrap 只是直接替换，对于 gap 功能类，我们建议将 col-gap- 替换为 gap-x-，将 row-gap- 替换为 gap-y-，以便一次性处理所有尺寸。

如果需要的话，为 fontWeight 启用 hover 和 focus 功能。

fontWeight 插件的 hover 和 focus 变体已经被默认禁用，因为像这样改变字体重量往往会导致布局混乱，所以无论如何都不会真正这么做。

如果您在项目中需要这些，请在您的 tailwind.config.js 文件中重新启用它们：

  // tailwind.config.js
  module.exports = {
    variants: {
      extend: {
+       fontWeight: ['hover', 'focus']
      }
    }
  }

用 flow-root 代替 clearfix

The clearfix class has been removed since flow-root is a simpler solution to the same problem in modern browsers. clearfix 类已经被删除，因为在现代浏览器中，flow-root 是一个更简单的解决方案。

- <div class="clearfix">
+ <div class="flow-root">
    <img class="float-left" src="..." alt="..." />
    <p>Lorem ipsum...</p>
  </div>

更新 font-wight 类的 100 和 200 权重

在 Tailwind CSS v2.0中，100 和 200 字体权重的类名已经改变。

字体权重	旧名称	新名称
100	`font-hairline`	`font-thin`
200	`font-thin`	`font-extralight`

由于 font-thin 在 v1 和 v2 中出现的权重不同，我们建议按以下顺序更新您的类：

在全局范围内用 font-extralight 替换 font-thin
在全局范围内用 font-thin 替换 font-hairline

用 ring 功能类替换 shadow-outline 和 shadow-xs

Tailwind CSS v2.0 引入了一套新的 ring 功能类，让您以一种自动与 Tailwind 的其他箱形阴影功能类相结合的方式添加轮廓阴影/焦点环。

这些都是比 shadow-outline 和 shadow-xs 类更好更强大的选择，所以我们已经删除了这些类。

用 ring 替换 shadow-outline：

- <div class="... focus:shadow-outline">
+ <div class="... focus:ring">

用 ring-1 ring-black ring-opacity-5 替换 shadow-xs：

- <div class="... shadow-xs">
+ <div class="... ring-1 ring-black ring-opacity-5">

另外，您也可以将 shadow-outline 和 shadow-xs 添加到您的配置文件中，而不影响您的 HTML。

module.exports = {
  theme: {
    extend: {
      boxShadow: {
        xs: '0 0 0 1px rgba(0, 0, 0, 0.05)',
        outline: '0 0 0 3px rgba(66, 153, 225, 0.5)',
      }
    }
  }
}

显式配置您的调色板

如果您已经使用了自定义的调色板，不需要改变，您可以安全地跳过这一步。

默认调色板在 Tailwind CSS v2.0 中已经发生了很大的变化，但并不是为了取代 v1 中的调色板。

如果您正在使用默认调色板，您应该显式的地配置它，用您的网站已经使用的颜色覆盖新的默认调色板。

下面是一个包含v1版默认颜色的 tailwind.config.js 文件的例子：

// tailwind.config.js
module.exports = {
  theme: {
    colors: {
      transparent: 'transparent',
      current: 'currentColor',

      black: '#000',
      white: '#fff',

      gray: {
        100: '#f7fafc',
        200: '#edf2f7',
        300: '#e2e8f0',
        400: '#cbd5e0',
        500: '#a0aec0',
        600: '#718096',
        700: '#4a5568',
        800: '#2d3748',
        900: '#1a202c',
      },
      red: {
        100: '#fff5f5',
        200: '#fed7d7',
        300: '#feb2b2',
        400: '#fc8181',
        500: '#f56565',
        600: '#e53e3e',
        700: '#c53030',
        800: '#9b2c2c',
        900: '#742a2a',
      },
      orange: {
        100: '#fffaf0',
        200: '#feebc8',
        300: '#fbd38d',
        400: '#f6ad55',
        500: '#ed8936',
        600: '#dd6b20',
        700: '#c05621',
        800: '#9c4221',
        900: '#7b341e',
      },
      yellow: {
        100: '#fffff0',
        200: '#fefcbf',
        300: '#faf089',
        400: '#f6e05e',
        500: '#ecc94b',
        600: '#d69e2e',
        700: '#b7791f',
        800: '#975a16',
        900: '#744210',
      },
      green: {
        100: '#f0fff4',
        200: '#c6f6d5',
        300: '#9ae6b4',
        400: '#68d391',
        500: '#48bb78',
        600: '#38a169',
        700: '#2f855a',
        800: '#276749',
        900: '#22543d',
      },
      teal: {
        100: '#e6fffa',
        200: '#b2f5ea',
        300: '#81e6d9',
        400: '#4fd1c5',
        500: '#38b2ac',
        600: '#319795',
        700: '#2c7a7b',
        800: '#285e61',
        900: '#234e52',
      },
      blue: {
        100: '#ebf8ff',
        200: '#bee3f8',
        300: '#90cdf4',
        400: '#63b3ed',
        500: '#4299e1',
        600: '#3182ce',
        700: '#2b6cb0',
        800: '#2c5282',
        900: '#2a4365',
      },
      indigo: {
        100: '#ebf4ff',
        200: '#c3dafe',
        300: '#a3bffa',
        400: '#7f9cf5',
        500: '#667eea',
        600: '#5a67d8',
        700: '#4c51bf',
        800: '#434190',
        900: '#3c366b',
      },
      purple: {
        100: '#faf5ff',
        200: '#e9d8fd',
        300: '#d6bcfa',
        400: '#b794f4',
        500: '#9f7aea',
        600: '#805ad5',
        700: '#6b46c1',
        800: '#553c9a',
        900: '#44337a',
      },
      pink: {
        100: '#fff5f7',
        200: '#fed7e2',
        300: '#fbb6ce',
        400: '#f687b3',
        500: '#ed64a6',
        600: '#d53f8c',
        700: '#b83280',
        800: '#97266d',
        900: '#702459',
      },
    }
  }
}

我们不建议更新现有网站以使用新的默认调色板。这些数字并不意味着可以转移，所以例如 v2 中的 bg-red-600 并不仅仅是 v1 中的 bg-red-600 的 "更好 "版本--它有不同的对比特性。如果您对您的网站的外观很满意，就没有必要花上几个小时来更新您的 HTML。旧的颜色也很好

显式配置您的 font-size

如果您已经使用了自定义的排版比例，则无需更改，您可以安全地跳过这一步。

在v2.0中，每个字体大小功能类默认都包含一个合理的特定行高，例如 text-sm 会自动设置 1.25rem 的行高。

如果您没有在 font-size功能类旁明确添加 leading 功能类，这将会改变您的网站在任何地方的外观。

解决这个问题的最快方法是显式配置您的 font-size 比例，使用 v1 的比例：

// tailwind.config.js
module.exports = {
  theme: {
    fontSize: {
      xs: '0.75rem',
      sm: '0.875rem',
      base: '1rem',
      lg: '1.125rem',
      xl: '1.25rem',
      '2xl': '1.5rem',
      '3xl': '1.875rem',
      '4xl': '2.25rem',
      '5xl': '3rem',
      '6xl': '4rem',
    },
  }
}

另外，您也可以检查您的 HTML，并在任何依赖继承行高的地方明确添加一个 leading 功能类。

- <p class="text-lg">...</p>
+ <p class="text-lg leading-normal">...</p>

更新默认主题键为 DEFAULT

在Tailwind CSS v1.x中， tailwind.config.js的各个主题部分的 default 关键字有时意味着 "不要给类名添加后缀"。

例如，这个配置：

// tailwind.config.js
module.exports = {
  theme: {
    borderRadius: {
      none: '0',
      sm: '0.125rem',
      default: '0.25rem',
      md: '0.375rem',
      lg: '0.5rem',
    },
  }
}

...会生成一个 border-radius 为 0.25rem 的 rounded 类，而不是一个 rounded-default 类。

在 Tailwind CSS v2.0 中，我们已经更新了所有对 default 的特殊用法，改为大写的 DEFAULT。

// tailwind.config.js
module.exports = {
  theme: {
    borderRadius: {
      none: '0',
      sm: '0.125rem',
      DEFAULT: '0.25rem',
      md: '0.375rem',
      lg: '0.5rem',
    },
  }
}

小写的 default 会像其他字符串一样被处理，所以在 borderRadius 下的默认值会在 Tailwind CSS v.2.0 中生成一个四舍五入的 default 类，您应该更新配置文件中所有 default 的用法，除非您真的想生成一个 {utility}-default 类。

您应该把配置文件中所有 default 的用法都更新为 DEFAULT，除非您真的想生成一个 {utility}-default 类，比如 cursor-default。

如果您不清楚您自己的配置需要做哪些改变，请参考完整的 default 配置，看看我们现在在哪些地方使用了 DEFAULT，哪些地方还在使用 default。

特意将浅层扩展移到顶层

在 Tailwind CSS v1.0 中，extend 下的主题变化被浅层次合并。所以这个配置会覆盖所有的紫色。

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: {
        purple: {
          light: '#E9D8FD',
          medium: '#9F7AEA',
          dark: '#553C9A',
        }
      }
    }
  }
}

在 v2.0 中，这些都是深度合并的，所以上面的配置仍然会生成默认的紫色-100到紫色-900色调，此外还有自定义的紫色-浅色、紫色-中色和紫色-深色。

在大多数情况下，这很有用，但如果您是依靠浅层合并，您会希望将您的自定义移动到顶层，并手动合并其他顶层颜色。

const defaultTheme = require('tailwindcss/defaultTheme')

module.exports = {
  theme: {
    colors: {
      ...defaultTheme.colors,
      purple: {
        light: '#E9D8FD',
        medium: '#9F7AEA',
        dark: '#553C9A',
      }
    }
  }
}

您可能不需要这样做。

更新依赖类顺序的 @apply 语句

在 v2.0 中，@apply 功能变得更加强大，但需要改变一些行为才能实现。

以前，类是按照它们在 CSS 中出现的顺序来应用的。

/* Input */
.my-class {
  @apply pt-5 p-4;
}

/* Output */
.my-class {
  padding-top: 1.25rem;
  padding: 1rem;
}

现在，类将按照它们在原始 CSS 中出现的顺序被应用。

/* Input */
.my-class {
  @apply pt-5 p-4;
}

/* Output */
.my-class {
  padding: 1rem;
  padding-top: 1.25rem;
}

这是为了确保行为与 HTML 中的行为一致。

<!-- Here `pt-5` still takes precedence even though it appears first. -->
<div class="pt-5 p-4">...</div>

如果您是依赖旧的行为，您可能会看到您的网站的渲染方式有一些差异。要解决这个问题，请使用多个 @apply 声明。

.my-class {
  @apply pt-5;
  @apply p-4;
}

这几乎不会影响那些不会去做奇怪事情的人。

在任何 @apply 语句中添加您配置的前缀

在 Tailwind CSS v1.0 中，即使您配置了一个前缀，您也可以 @apply 无前缀的功能类。

这在 v2.0 中不再支持，所以如果您为您的网站配置了一个前缀（如 tw- ），您需要确保在您使用 @apply 时包含这个前缀。

.my-class {
  @apply tw-p-4 tw-bg-red-500;
}

删除 @apply 语句中的前导点

我们曾经支持用可选的 . 字符来编写 @apply 语句。

.my-class {
  @apply .p-4 .bg-red-500;
}

我们不再支持这个了，所以更新任何 @apply 语句并删除点。

.my-class {
  @apply p-4 bg-red-500;
}

在 textOverflow 下启用任何 truncate 变体

truncate 功能类现在是 textOverflow 核心插件的一部分，所以如果您为了使用 truncate 类而为 wordBreak 插件启用了任何额外的变体（比如 group-hover），您现在也要为 textOverflow 启用这些变体。

  // tailwind.config.js
  module.exports = {
    variants: {
      wordBreak: ['responsive', 'group-hover'],
+     textOverflow: ['responsive', 'group-hover'],
    }
  }

滚动触摸和自动滚动功能已移除

由于 iOS 13 不再支持 -webkit-overflow-scrolling 属性，我们已经从 v2.0 中删除了这两个功能。

如果您仍然需要它们，因为您正在为老版本的 iOS 构建一些东西，您可以自己将它们添加为自定义功能。

@tailwind base;
@tailwind components;
@tailwind utilities;

@layer utilities {
  @responsive {
    .scrolling-touch {
      -webkit-overflow-scrolling: touch;
    }
    .scrolling-auto {
      -webkit-overflow-scrolling: auto;
    }
  }
}

更新从数组中读取的 theme 函数引用

在 v2.0 中，theme 功能（在 CSS、tailwind.config.js文件和插件 API 中）更加智能，不再需要您手动加入数组或明确访问第一个索引。

// tailwind.config.js
const plugin = require('tailwindcss/plugin')

module.exports = {
  theme: {
    fontSize: {
      // ...
      xl: ['20px', { lineHeight: '28px' }]
    }
  },
  plugins: [
    plugin(({ addBase, theme }) => {
      addBase({
        h1: {
          // Before
          fontSize: theme('fontSize.xl')[0],
          fontFamily: theme('fontFamily.sans').join(','),

          // Now
          fontSize: theme('fontSize.xl'),
          fontFamily: theme('fontFamily.sans'),
        }
      })
    })
  ]
}

如果出于任何原因您想访问原始数据结构，您可以使用 config 函数来代替。

在空格或分割元素内的任何模板标签中添加隐藏功能

我们曾经有一个特殊的规则，在使用 space-x/y 和 divide-x/y 功能类时忽略模板元素，主要是为了让 Alpine.js 用户更加方便。

我们已经更新了工作方式，不再对模板元素进行特殊处理，而是明确地忽略任何具有隐藏属性的元素。

要更新您的代码以适应这一变化，只需在您的 template 标签中添加 hidden 即可：

  <div class="space-y-4">
-   <template x-for="item in items">
+   <template x-for="item in items" hidden>
      <!-- ... -->
    </template>
  </div>

更新清除选项以匹配 PurgeCSS 3.0

在内部，我们已经升级到了 PurgeCSS 3.0，所以您通过选项键传递到 PurgeCSS 的任何原始选项都需要更新，以匹配 PurgeCSS 3.0 中的选项。

例如，如果您使用的是 whitelist，您就需要更新为 safelist：

  // tailwind.config.js
  module.exports = {
    purge: {
      content: [
        // ...
      ],
      options: {
-       whitelist: ['my-class']
+       safelist: ['my-class']
      }
    }
  }

如果您没有使用 option 键，您不需要做任何事情。

如果使用自定义的 PurgeCSS 提取器，则禁用 preserveHtmlElements

在 v1.0 中，如果您使用一个自定义的提取器，Tailwind 忽略了 preserveHtmlElements 选项。这个选项现在在 v2.0 中得到了适当的尊重，所以如果您想禁用它，您需要显式地这样做：

  // tailwind.config.js
  module.exports = {
    purge: {
      content: [
        // ...
      ],
+     preserveHtmlElements: false,
      options: {
        defaultExtractor: () => {
          // ...
        }
      }
    }
  }

如有需要，请在任何 keyframe 引用前加上前缀

如果您已经在您的 tailwind.config.js 文件中配置了一个前缀，Tailwind v2.0 将自动应用该前缀到您的主题中的任何 keyframes 声明。

如果您在自定义 CSS 中引用任何配置的 keyframes，您需要确保添加您的前缀。

  .my-class {
-   animation: spin 1s infinite;
+   animation: tw-spin 1s infinite;
  }

这仅在您配置了前缀 and 且引用自定义 CSS 文件中已配置的 keyframes 时才重要。如果这影响到整个星球上的两个以上的人，我将绝对感到惊讶。