banner
cos

cos

愿热情永存，愿热爱不灭，愿生活无憾
github
tg_channel
bilibili
首頁封存关于♪歌单NFT作品集

Tailwind CSS v4.0 升級與 Astro 5.2 專案遷移記錄

#前端#astro#Tailwind#CSS55
AI 翻譯
這篇文章透過AI由簡體中文翻譯成繁體中文。查看原文
AI 生成的摘要
Tailwind CSS v4.0 引入了多項新特性和改進，包括： - **高性能引擎**：完整構建速度提升5倍，增量構建速度超過100倍。 - **現代化的 Web 設計**：支持前沿 CSS 特性，如 @property 和 color-mix()。 - **簡化安裝**：依賴項減少，僅需一行代碼即可安裝。 - **自動內容檢測**：自動發現所有模板文件，無需配置。 - **CSS 主題變量**：所有設計令牌以原生 CSS 變量形式暴露。 - **容器查詢**：根據容器大小為元素設計樣式。 - **3D 變換實用程序**：支持在 HTML 中進行 3D 變換。 - **擴展的漸變 API**：支持線性、徑向和圓錐漸變。 - **新實用程序和變體**：包括 inset-shadow、field-sizing、color-scheme 等。 此外，還提供了全面的升級指南和自動升級工具，以便現有項目能夠輕鬆遷移到新版本。

自用小記。

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 [email protected]
npm info using [email protected]
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 function

npm 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"),
  ],
};

然後起一下試試：

> [email protected] dev /Users/cosine/Documents/Programming/cos-space
> astro dev

Package subpath './nesting/index.js' is not defined by "exports" in /Users/cosine/Documents/Programming/cos-space/node_modules/.pnpm/@[email protected][email protected]_@[email protected][email protected][email protected][email protected]._5qh5alcn5ztelwntajptz64i4q/node_modules/tailwindcss/package.json imported from /Users/cosine/Documents/Programming/cos-space/node_modules/.pnpm/@[email protected][email protected]_@[email protected][email protected][email protected][email protected]._5qh5alcn5ztelwntajptz64i4q/node_modules/@astrojs/tailwind/dist/index.js
  Stack 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/loader:359:25)
    at ModuleLoader.resolve (node:internal/modules/esm/loader:322:34)
    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-check
 import 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/config
 export 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
載入中......
此文章數據所有權由區塊鏈加密技術和智能合約保障僅歸創作者所有。