--- title: "Tailwind CSS v3とv4の違い｜破壊的変更と移行手順をv4.3.3の実ビルドで検証" url: "https://www.issoh.co.jp/tech/details/5060/" published: 2025-01-28 updated: 2026-09-23 categories: ["Tailwind CSS"] publisher: "株式会社一創" --- # Tailwind CSS v3とv4の違い｜破壊的変更と移行手順をv4.3.3の実ビルドで検証 Tailwind CSS v4.0 は2025年1月22日にリリースされ、npmの最新版は2026年9月23日時点で 4.3.3（2026年7月16日公開）です。v3からの移行でつまずくのは、削除されてビルドが落ちるクラスではなく、**クラス名が残ったまま出力されるCSSだけが変わる箇所**と、**エラーを出さずに無効なCSSへ変換される旧記法**です。この記事では v3.4.19 と v4.3.3 を同じ環境に入れて同一クラスをビルドし、生成CSSを突き合わせた実測をもとに、差分・移行手順・判断基準を整理します。 ## まとめ：v3とv4の違いで押さえる5点 先に結論を挙げます。 - **設定の置き場所が変わった**。`tailwind.config.js` は自動で読まれなくなり、テーマはCSSの `@theme` に書く。JS設定を続けるなら `@config` で明示的に読み込む。 - **ビルドが通るのに見た目だけ変わるクラスがある**。`shadow-sm` `rounded-sm` `blur-sm` は名前が一段ずつずれ、`ring` は3pxから1pxへ、`border` の既定色は gray-200 から currentColor へ変わった。クラス名は残るのでビルドは成功する。 - **旧記法はエラーにならず無効なCSSになる**。`bg-[--brand]` は v4.3.3 で `background-color: --brand;` という効かない宣言を出力する。 - **対応ブラウザが切り上がった**。公式の対応対象はSafari 16.4・Chrome 111・Firefox 128以降。v4.1では旧ブラウザ向けフォールバックも改善されたが、それ以前のブラウザで全機能が同等に動く保証はない。 - **v3は放置されていない**。npmの `v3-lts` タグは 3.4.19（2025年12月10日公開）で、v4.0の公開後にもv3系のリリースが出ている。古いブラウザやSassが外せない案件は据え置きが現実的な選択肢になる。 以下、それぞれを実測値と公式の記述で裏づけていきます。 ## v3とv4を分ける4つの土台変更 ### 設定方式の変更：JavaScriptからCSSへ v3では `tailwind.config.js` にテーマと `content` を書き、CSS側は `@tailwind` ディレクティブ3行で読み込む構成でした。v4はこれをCSSに一本化します。 ``` /* v3.4 */ @tailwind base; @tailwind components; @tailwind utilities; /* v4.3 */ @import "tailwindcss"; @theme { --color-brand: oklch(0.7 0.15 250); --breakpoint-3xl: 120rem; } ``` `--color-brand` を定義すれば `bg-brand` や `text-brand` が使えるようになると同時に、Tailwindを通さない素のCSSからも `var(--color-brand)` で参照できます。ただし `@theme` に書いた変数が常にCSSへ出るわけではありません。v4.3.3 で確かめたところ、既定ではユーティリティとして使われた変数だけが出力され、どこからも参照されていない変数は省かれます。JavaScriptから読むためだけに定義した変数を消さないためには `@theme static` を使います。v3にあった `resolveConfig` は削除されており、JavaScript側でテーマ値が要るときは `getComputedStyle(document.documentElement)` で読む形に変わりました。 JS設定は互換のため残っていますが、自動検出はされません。既存の `tailwind.config.js` を使い続けるなら、CSSから明示的に読み込みます。 ``` @import "tailwindcss"; @config "../../tailwind.config.js"; ``` ただし移せない設定があります。公式アップグレードガイドは `corePlugins`・`safelist`・`separator` の3つを「v4.0ではサポートされない」と明記しています。このうち safelist の代替は `@source inline()` ですが、これが追加されたのは v4.1.0（2025年4月1日公開）です。v4.0系には `@source inline()` はありませんが、必要なクラス名を列挙したファイルを `@source` で走査対象に追加する方法は使えました。当時の移行記事を読むときは、対応する版と記法を確認してください。 ### ビルド性能の比較と測定条件 [公式ブログのベンチマーク](https://tailwindcss.com/blog/tailwindcss-v4#new-high-performance-engine)は、自社製品Catalystを対象にした中央値として次の数字を出しています。 | 計測条件 | v3.4 | v4.0 | 倍率 | | -------------- | ----- | ----- | ----- | | フルビルド | 378ms | 100ms | 3.78x | | 増分ビルド（新規CSSあり） | 44ms | 5ms | 8.8x | | 増分ビルド（新規CSSなし） | 35ms | 192µs | 182x | 「100倍速い」という表現が独り歩きしていますが、182倍が出るのは**新しいクラスが1つも増えていない再ビルド**という条件付きです。新規CSSが増えない再ビルドと、CIなどのクリーンビルドでは、比較すべき計測条件が異なります。3.78倍はCatalystでのフルビルドの測定値であり、各プロジェクトのCIでも同じ倍率になるとは限りません。 最小構成で計測すると数字の桁が変わります。検証条件は macOS（Intel x86\_64）・Node.js v26.5.0、入力はクラス10個を含むHTML 1枚のみ、出力先は `/dev/null`、ウォームアップとして各版1回実行したあとに `tailwindcss@3.4.19` と `@tailwindcss/cli@4.3.3` のCLIをそれぞれ5回ずつ実行し、`time` の real 値を平均したものです。結果は v3 が1.526秒、v4 が0.656秒でした。Node.jsのプロセス起動時間を含む値なので、公式ベンチマークとは測定範囲が異なります。この比較だけではプロジェクト規模と高速化倍率の関係までは判断できず、規模の影響を調べるには同じ測定方法で入力規模を変えた比較が必要です。 付随して、v4はインポート解決とベンダープレフィックス付与を内蔵しました。`postcss-import` と `autoprefixer` は設定から外せます。 ### 対応ブラウザの下限と旧版向けフォールバック [公式アップグレードガイド](https://tailwindcss.com/docs/upgrade-guide)は「Tailwind CSS v4.0 is designed for modern browsers and targets Safari 16.4, Chrome 111, and Firefox 128」と書き、`@property` と `color-mix()` をコア機能が使っているため「will not work in older browsers」と続けています。Safari 16.4 は2023年3月27日リリースなので、この下限はiOS 16.4以降の端末に相当します。 ただし「それ以前では一切表示されない」と読むのは行き過ぎです。v4.1 で旧ブラウザ向けのフォールバックが入り、公式ブログは oklab で定義した色が古いSafariでも描画されること、`@property` に依存する影・変形・グラデーションが古いSafariとFirefoxでも動くことを挙げています。同じ記事が「Tailwind CSS v4 is still designed for modern browsers like Safari 16.4 and up」と念を押したうえで「at least now your sites will render and be usable in older browsers」と書いており、**公式の対応対象は変わらないまま、劣化の仕方が穏やかになった**というのが正確な理解です。 したがって、iOS 16.3以前を公式サポート対象に含む案件では「If you need to support older browsers, we recommend sticking with v3.4 for now」という公式推奨どおり v3.4 の継続が基本で、それでもv4へ上げるなら対象端末での実機確認が前提になります。ガイドは互換モードを「actively exploring」と書いていますが、2026年9月時点で提供はされていません。 ### ビルドツール別のパッケージ構成 v3では `tailwindcss` ひとつがPostCSSプラグインでもCLIでもありました。v4はそれぞれ別パッケージです。 | 用途 | v3.4 | v4.3 | | ------- | --------------- | -------------------- | | PostCSS | tailwindcss | @tailwindcss/postcss | | Vite | PostCSS経由 | @tailwindcss/vite | | CLI | npx tailwindcss | npx @tailwindcss/cli | | webpack | PostCSS経由 | @tailwindcss/webpack | webpack専用プラグインは v4.2.0（2026年2月18日）で追加された新顔です。これらは本体と同じ版番号で並行リリースされており、2026年9月23日時点ではいずれも 4.3.3 です。Viteを使っているなら、PostCSSプラグイン経由ではなく `@tailwindcss/vite` へ移すことを公式が推奨しています。 ## ビルドは通るのに見た目だけ変わるクラス 移行で最も厄介なのがこの層です。クラス名がv4でも有効なので、ビルドもリントも通り、ブラウザで見て初めて気づきます。以下はすべて v3.4.19 と v4.3.3 で同じHTMLをビルドし、生成CSSを直接比較した結果です。 ### shadow・rounded・blurの名称と値の対応 v4は「素の名前（`shadow`・`rounded`・`blur`）」にも値の名前を与える方針でスケールを振り直しました。その結果、v3の値がひとつ小さい名前へスライドしています。v4.3.3 同梱の `theme.css` から実際の値を抜くと対応がはっきりします。 | v3のクラス | v3の値 | v4で同じ値になるクラス | | ---------- | ------------------------------ | ------------ | | shadow-sm | 0 1px 2px 0 rgb(0 0 0 / 0.05) | shadow-xs | | shadow | 0 1px 3px 0 rgb(0 0 0 / 0.1) 他 | shadow-sm | | rounded-sm | 0.125rem | rounded-xs | | rounded | 0.25rem | rounded-sm | | blur-sm | 4px | blur-xs | | blur | 8px | blur-sm | 実際に v4.3.3 で `shadow-sm` をビルドすると、出力される `--tw-shadow` は `0 1px 3px 0 …, 0 1px 2px -1px …` でした。v3で書いた `shadow-sm` をそのまま残すと、影が一段濃くなります。`drop-shadow-*` と `backdrop-blur-*` も同じ規則でずれます。 ### ring と outline の既定値 v3の `ring` は 3px のリングを既定色 blue-500 で描いていました。v4.3.3 の生成CSSでは幅が `calc(1px + var(--tw-ring-offset-width))`、色が `var(--tw-ring-color, currentcolor)` です。border や outline と揃えるための変更で、v3と同じ見た目が要るなら `ring-3` と色指定の両方を書き足します。 `outline-none` はもっと分かりにくく壊れます。v3は「透明な2pxのアウトライン」を出していました。強制カラーモードでフォーカス位置を失わせないための実装です。 ``` /* v3.4.19 の出力 */ .outline-none { outline: 2px solid transparent; outline-offset: 2px; } /* v4.3.3 の出力 */ .outline-none { --tw-outline-style: none; outline-style: none; } ``` v4の `outline-none` は名前どおりアウトラインを消します。v3の挙動に相当するのは `outline-hidden` です。`focus:outline-none` を機械的に残すと、アクセシビリティ上の配慮が黙って外れるので、この置換だけは優先度を上げてください。 プロジェクト全体をv3の値に戻したい場合は、公式が互換用のテーマ変数を用意しています。ただしガイド自身が「compatibility reasons のためであり v4.0 の慣用的な書き方ではない」と注記しているので、移行期間の一時措置として使う前提です。 ``` @theme { --default-ring-width: 3px; --default-ring-color: var(--color-blue-500); } ``` ### border の既定色と space-y-\* のセレクタ v3のPreflightは `*, ::before, ::after` に `border-color: #e5e7eb`（gray-200）を当てていました。v4.3.3 の出力を見ると該当箇所は `border: 0 solid` だけで、色指定がありません。つまり currentColor です。`border` とだけ書いて色を指定していない箇所は、テキスト色の枠線に変わります。全体をv3の見た目へ戻すなら、ベースレイヤーで色を戻します。 ``` @layer base { *, ::after, ::before, ::backdrop, ::file-selector-button { border-color: var(--color-gray-200, currentColor); } } ``` `space-y-*` はセレクタごと作り替えられました。v3は後続兄弟結合子 `~` を使って上マージンを当てていましたが、v4は最後の子以外に下マージンを当てます。次のコードは差分に関係する宣言の抜粋で、変数の初期化などは省略しています。 ``` /* v3.4.19 */ .space-y-4 > :not([hidden]) ~ :not([hidden]) { margin-top: calc(1rem * calc(1 - var(--tw-space-y-reverse))); } /* v4.3.3 */ :where(.space-y-4 > :not(:last-child)) { margin-block-end: calc(calc(var(--spacing) * 4) * calc(1 - var(--tw-space-y-reverse))); } ``` ここで見落としやすいのが `:where()` です。公式ガイドのコード例には `:where()` が書かれていませんが、v4.3.3 が実際に吐くCSSは `:where()` で包まれており、**詳細度が0になっています**。自前のCSSで上書きしやすくなった一方、これまで詳細度の高さに助けられていた指定は逆転する可能性があります。あわせてマージンの向きが上から下へ、物理プロパティから論理プロパティへ変わるため、インライン要素に `space-x-*` を当てていた箇所や子要素に個別のマージンを足していた箇所は目視確認が要ります。公式は解決策として、`flex` か `grid` に変えて `gap` を使う移行を勧めています。`divide-x-*` と `divide-y-*` も同じ理由で同じ変更が入っています。 色そのものも変わっています。既定パレットの記述が `rgb` から `oklch` になり、sRGBより広い色域を使えるようになりました。ただしこれは「派手になる」変更ではなく、公式はv3の色バランスを保つよう再設計したと説明しており、アップグレード時に破壊的変更として体感される想定ではないとしています。色の差分を確認する際は、ブランドカラーを使う画面に加え、通常のsRGB環境とP3対応環境で主要画面の表示を比較してください。 ## エラーを出さずに無効なCSSになる旧記法 前章は「値が変わる」話でしたが、こちらは「出力されたCSSが効かない」話です。ビルドログには何も出ません。 ### CSS変数を任意値で渡す記法の変更と移行先 v3では角括弧にCSS変数名を直接書けました。v4は括弧を丸括弧に変えています。両方を同じHTMLに書いて v4.3.3 でビルドすると、違いが一目で分かります。 ``` /* v4.3.3 が実際に出力したCSS */ .bg-\(--brand\) { background-color: var(--brand); } .bg-\[--brand\] { background-color: --brand; } ``` 旧記法の `bg-[--brand]` は、v4では「`--brand` という名前の任意値」として素直に解釈され、`background-color: --brand;` という無効な宣言になります。クラスは生成されるのでビルドは成功し、CSSファイルにも行は存在し、ただ背景色だけが付きません。アップグレードツールはこの書き換えを自動化しますが、文字列連結でクラス名を組み立てている箇所は拾えないので、`-[--` をリポジトリ全体でgrepして潰すのが確実です。 ### 任意値のカンマ変換廃止とアンダースコアへの移行 v3は `grid-cols-*`・`grid-rows-*`・`object-*` の任意値に限り、カンマを空白へ置き換えていました。v2との互換のための特別扱いで、v4では無くなっています。 ``` /* v4.3.3 が実際に出力したCSS */ .grid-cols-\[max-content\,auto\] { grid-template-columns: max-content,auto; } ``` カンマがそのまま残り、`grid-template-columns` としては解釈できない値になります。空白はアンダースコアで表すのが v4 の書き方なので、`grid-cols-[max-content_auto]` に直します。 ### 非推奨クラスの公式記載とv4.3.3での出力差 v4.3.3 で実際にビルドして、削除対象とされるクラスの出力可否を確かめました。結果は割れます。 | クラス | v4.3.3での出力 | 置き換え先 | | ----------------- | ---------- | -------------------- | | bg-opacity-50 | 出力されない | bg-black/50 | | text-opacity-50 | 出力されない | text-black/50 | | ring-opacity-50 | 出力されない | ring-black/50 | | flex-shrink-0 | 出力される | shrink-0 | | flex-grow-0 | 出力される | grow-0 | | overflow-ellipsis | 出力される | text-ellipsis | | decoration-slice | 出力される | box-decoration-slice | 透明度系の `*-opacity-*` は本当に消えており、該当クラスはCSSに1行も現れません。一方、公式ガイドが同じ「削除された非推奨ユーティリティ」の表に並べている `flex-shrink-0` や `overflow-ellipsis` は、v4.3.3 では依然としてCSSが生成されます。**「ドキュメント上は削除、実装上は動く」という状態なので、動作確認では移行漏れを検出できません**。将来のマイナー版で本当に落ちる可能性を考えるなら、目視ではなくgrepで機械的に洗い出して置換しておくのが安全です。 ## 移行手順：アップグレードツールで済む範囲と手作業の範囲 ### アップグレードツールの実行条件と処理範囲 公式のアップグレードツールは、依存関係の更新・設定ファイルのCSSへの移行・テンプレート内のクラス書き換えまでをまとめて実行します。 ``` npx @tailwindcss/upgrade ``` 前提は Node.js 20以上です。ガイドは「新しいブランチで実行し、差分を丁寧にレビューしてブラウザで動作確認すること」を明示的に勧めています。パッケージ版は本体と揃っており、2026年9月23日時点で 4.3.3 です。前章のクラス名変更や記法変更の大半はここで自動処理されるので、手で直し始める前に一度流してください。 ### 自動移行後に必要な手動確認 自動化の外に残るのは、機械的な文字列置換では判断できない箇所です。 - **コンポーネント内の `@apply`**。Vue・Svelte・Astro の `