Tailwind CSS v4.0 升级与 Astro 5.2 项目迁移记录

本文博客链接 https://ysx.cosine.ren/tailwind-update-v4-migrate

自用小记。

Tailwind CSS v4.0 - Tailwind CSS

• 新的高性能引擎 - 完整构建的速度速度快 5 倍，增量构建的速度快于 100 倍以上 —— 以微秒为单位进行测量。
• 为现代 Web 设计 - 建立在前沿的 CSS 特性之上，使用级联层、 @property 和 color-mix() 等前沿 CSS 特性注册自定义属性。
• 简化的安装 - 较少的依赖项，零配置，只需要 CSS 文件中的一行代码。
• 第一方 Vite 插件 - 紧密集成，可实现最高性能和最低配置。
• 自动内容检测 - 所有模板文件都是自动发现的，无需配置。
• 内置导入支持 - 无需额外工具即可捆绑多个 CSS 文件。
• CSS-First 配置 - 重新设计的开发人员体验，您可以直接在 CSS 而不是 JavaScript 配置文件中自定义和扩展框架。
• CSS 主题变量 - 您的所有 design tokens 都以原生 CSS 变量的形式暴露，因此您可以在任何地方访问它们。
• 动态实用程序值和变体 - 不再需要猜测间距中存在哪些值，也不再需要为基本数据属性等扩展配置。
• 现代化的 P3 调色板 - 重新设计的更加生动的调色板，充分利用了现代展示技术。
• 容器查询 - 可使用容器查询根据容器大小为元素设计样式，不再需要插件
• 新的 3D 变换实用程序 - 直接在 HTML 中的 3D 空间中变换元素，添加了用于进行 3D 变换的 API，例如 rotate-x-* ， rotate-y-* ， scale-z-* ， translate-z-* 和更多。
• 扩展的梯度 API - 径向和圆锥梯度，插值模式等。现在，线性梯度将角度作为值支持，因此您可以使用bg-linear-45等实用程序以 45 度角创建梯度。将bg-gradient-*重命名为bg-linear-*
• @starting-style support - 新的starting变体增加了对新的 CSS @starting-style 功能的支持，从而在首次显示元素时可以过渡元素属性：
• not-* variant - 仅在元素不匹配另一个变体，自定义选择器或媒体或功能查询时样式。
• 甚至更多的新实用程序和变体，包括对color-scheme的支持， field-sizing ，复杂的阴影， inert等。

更多新变体

• 新的 inset-shadow-* 和 inset-ring-* 实用程序 - 使得在一个元素上最多可以堆叠四层盒子阴影。
• 新的 field-sizing 实用程序 - 用于自动化的文本列，而无需编写单行 JavaScript。
  • 使用field-sizing-content，允许表单控件根据内容调整其大小
  • 使用field-sizing-fixed 固定尺寸：
• 新的 color-scheme - 参考 使用 light-dark() 的 CSS 配色方案相关颜色
• 新的 font-stretch 实用程序 - 用于仔细调整支持不同宽度的可变字体。
• 新的 inert 变体 - inert变体使您可以样式的元素标记为inert属性，这对于添加视觉提示很有用，可以清楚地表明内容的各个部分不是交互式的。
• 新的 nth-* 变体 - 使用 nth-* 和 nth-last-* 变体来根据孩子在列表中的位置设置样式，您可以在默认情况下将您想要的任何数字传递给这些数字，并使用任意值对 nth-[2n+1_of_li] 等更复杂的表达式使用任意值。 eg: nth-3:underline nth-last-5:underline nth-last-of-type-6:underline
  • 有关可用伪类变体的完整列表，请参见伪类参考资料。
• 新的 in-* 变体 - 非常类似于 group-* ，但无需 group 类。
  • in-* 变体响应任何父代的状态变化，所以如果你想要更精细的控制，就需要使用 group 来代替。
• 支持:popover-open - 使用现有的 open 式变体也针对 open popovers.
• 新的后代变体- 用于造型所有后代元素，无论好坏。
  • 与 * 一样，** 变体也可用于为元素的子元素设置样式。主要区别在于 ** 将对所有后代应用样式，而不仅仅是直接子代。当你将它与另一个变体结合使用，以缩小选择范围时，这一点尤其有用

迁移记录

对于现有项目，我们发布了一份全面的升级指南，并构建了一个自动升级工具，以尽快和无痛地使用最新版本。

一个小项目先试试水，执行自动化迁移指令。

npx @tailwindcss/upgrade@next

迁移输出如下

≈ tailwindcss v4.0.2
│ Searching for CSS files in the current directory and its subdirectories…
│ ↳ Linked `./tailwind.config.js` to `./src/styles/theme/shadcn.css`
│ Migrating JavaScript configuration files…
│ ↳ The configuration file at `./tailwind.config.js` could not be automatically migrated to the new CSS configuration format, so your CSS has been
│   updated to load your existing configuration file.
│ Migrating templates…
│ ↳ Migrated templates for configuration file: `./tailwind.config.js`
│ Migrating stylesheets…
│ ↳ Migrated stylesheet: `./src/styles/theme/shadcn.css`
│ Migrating PostCSS configuration…
│ ↳ Installed package: `@tailwindcss/postcss`
│ ↳ Removed package: `autoprefixer`
│ ↳ Removed package: `postcss-import`
│ ↳ Migrated PostCSS configuration: `./postcss.config.js`
│ Updating dependencies…
│ ↳ Updated package: `prettier-plugin-tailwindcss`
│ ↳ Updated package: `tailwindcss`
│ Verify the changes and commit them to your repository.
npm verb exit 0
npm info ok

可以看出自动完成了大部分工作，包括 flex-grow -> grow / flex-shrink -> shrink 等类名更新，这就是成功迁移了，嗯，貌似表面上没出什么意外，再试试另一个 astro 5.1 项目的升级，先莽一下更新脚本。

% sudo npx @tailwindcss/upgrade@next
npm verb cli /usr/local/bin/node /usr/local/lib/node_modules/npm/bin/npm-cli.js
npm info using npm@10.5.0
npm info using node@v20.12.2
npm verb title npm exec @tailwindcss/upgrade@next
npm verb argv "exec" "--" "@tailwindcss/upgrade@next"
npm verb logfile logs-max:10 dir:/Users/cosine/.npm/_logs/2025-02-03T10_01_41_235Z-
npm verb logfile /Users/cosine/.npm/_logs/2025-02-03T10_01_41_235Z-debug-0.log
npm sill logfile start cleaning logs, removing 1 files
npm sill logfile done cleaning log files
npm http fetch GET 200 https://registry.npmjs.org/@tailwindcss%2fupgrade 489ms (cache updated)
≈ tailwindcss v4.0.2│ Searching for CSS files in the current directory and its subdirectories…│ ↳ Linked `./tailwind.config.mjs` to `./src/styles/global/tailwind.css`│ Migrating JavaScript configuration files…│ ↳ Could not load the configuration file: undefined is not a functionnpm verb exit 1
npm verb code 1

很好，报错 Could not load the configuration file: undefined is not a function , 查了下是有插件不兼容。(Could not load the configuration file: v is not a function · tailwindlabs/tailwindcss · Discussion #15781 · GitHub)

看了一下之前迁移成功的项目里有这两个插件：tailwindcss-animate 和 @tailwindcss/typography

出问题的 astro 项目里多了一个 tailwind-clip-path 插件，注释后就正常执行了。

// tailwind.config.js
module.exports = {plugins: [require("@tailwindcss/container-queries"),require("tailwindcss-animate"),// require("tailwind-clip-path"),require("@tailwindcss/typography"),],
};

然后起一下试试：

> cos-space@0.0.1 dev /Users/cosine/Documents/Programming/cos-space
> astro devPackage subpath './nesting/index.js' is not defined by "exports" in /Users/cosine/Documents/Programming/cos-space/node_modules/.pnpm/@astrojs+tailwind@5.1.4_astro@5.1.1_@types+node@22.10.5_jiti@2.4.2_rollup@4.29.1_terser@5.37._5qh5alcn5ztelwntajptz64i4q/node_modules/tailwindcss/package.json imported from /Users/cosine/Documents/Programming/cos-space/node_modules/.pnpm/@astrojs+tailwind@5.1.4_astro@5.1.1_@types+node@22.10.5_jiti@2.4.2_rollup@4.29.1_terser@5.37._5qh5alcn5ztelwntajptz64i4q/node_modules/@astrojs/tailwind/dist/index.jsStack trace:at exportsNotFound (node:internal/modules/esm/resolve:304:10)at packageResolve (node:internal/modules/esm/resolve:837:14)at defaultResolve (node:internal/modules/esm/resolve:1157:11)at ModuleLoader.resolve (node:internal/modules/esm/loader:359:25)at ModuleLoader.import (node:internal/modules/esm/loader:322:34)ELIFECYCLE  Command failed with exit code 1.

很好，我就知道 astro 里的没那么简单迁移，查一下 astro/packages/integrations/tailwind/CHANGELOG.md at main · withastro/astro · GitHub Tailwind CSS 现在提供了一个 Vite 插件，这是在 Astro 中使用 Tailwind 4 的首选方法。卸载原来的 @astrojs/tailwind ，然后按照 tailwind 文档进行手动安装。

嗯，还得升一下 astro 版本到 Astro 5.2 | Astro

npx @astrojs/upgrade

pnpm rm @astrojs/tailwind
pnpm i tailwindcss @tailwindcss/vite

成功啦，对比一下配置文件

diff --git a/astro.config.mjs b/astro.config.mjs
index bf8e9b1..20513bd 100644
--- a/astro.config.mjs
+++ b/astro.config.mjs
@@ -1,22 +1,17 @@// @ts-checkimport react from '@astrojs/react';
-import tailwind from '@astrojs/tailwind';import { siteConfig } from './src/constants/site-config';import icon from 'astro-icon';import { defineConfig } from 'astro/config';import svgr from 'vite-plugin-svgr';import umami from '@yeskunall/astro-umami';
+import tailwindcss from '@tailwindcss/vite';// https://astro.build/configexport default defineConfig({site: siteConfig.site,integrations: [react(),
-    tailwind({
-      // 允许在 Tailwind 的语法基础上编写嵌套的 CSS 声明
-      nesting: true,
-      applyBaseStyles: false,
-    }),icon({include: {gg: ['*'],
@@ -35,7 +30,7 @@ export default defineConfig({enabled: true,},vite: {
-    plugins: [svgr()],
+    plugins: [svgr(), tailwindcss()],},trailingSlash: 'never',});

diff --git a/tailwind.config.mjs b/tailwind.config.mjs
index a7de2d0..28e5899 100644
--- a/tailwind.config.mjs
+++ b/tailwind.config.mjs
@@ -140,10 +140,5 @@ export default {},},},
-  plugins: [
-    require('@tailwindcss/container-queries'),
-    require('tailwindcss-animate'),
-    require('tailwind-clip-path'),
-    require('@tailwindcss/typography'),
-  ],
+  plugins: [require('@tailwindcss/container-queries'), require('tailwindcss-animate'), require('@tailwindcss/typography')],};

原来的插件失效了，@plugin 引入也不行，不过可以直接写在 css 里问题不大，还有就是 layer 层级问题会导致一些样式继承的问题，总体来说这俩小项目迁起来倒是没什么问题，后面迁移就持续更新这篇文章吧。

总结升级问题解决方案

问题一：Astro PostCSS 配置冲突

Error: Package subpath './nesting/index.js' is not defined by "exports" in...

应对策略：

1. 升级 Astro 至 5.2+ 版本 npx @astrojs/upgrade
2. 卸载 @astrojs/tailwind
3. 清理旧版 PostCSS 插件依赖
4. 按照 tailwind 文档进行手动安装，安装 tailwindcss @tailwindcss/vite / astro add tailwind