Tailwind CSS v3→v4 移行でスタイルが効かない・崩れる時の原因と対処【逆引き】

「Tailwind CSS を v4 に上げたら、いきなり画面が崩れた」——そんな経験、ありませんか？ v4 は 2025 年 1 月にリリースされ、Rust 製の新エンジン（Oxide）とCSSファースト設定への大きな作り変えが入りました。速くて快適な反面、v3 の書き方のまま上げると「ボーダーが消えた」「フォーカス枠が細くなった」「そもそもビルドが通らない」といったハマりが多発します。

この記事では、「崩れた症状」から原因と対処を引ける逆引き形式で、v3→v4 移行の定番のつまずきをまとめます。コピペできる修正コードつきなので、今まさに崩れて困っている方はまず下の早見表から該当箇所へ飛んでください。

まず結論：症状別・逆引き早見表

v4 で「効かない・崩れる」の大半は、次の6パターンのどれかです。自分の症状に近いものから読んでください。

個別の対処に入る前に、まず「そもそも手作業で直すべきなのか」を確認しておきましょう。

大前提：まず公式の自動アップグレードツールを試す

v3→v4 の移行は、まず公式のアップグレードツールに任せるのが正解です。設定の書き換えやリネームされたクラスの置換を、かなりの部分まで自動でやってくれます。

# 事前に新しいブランチを切っておく（差分を確認しながら進めるため）
git switch -c chore/tailwind-v4

# アップグレードツールを実行（Node.js 20 以上が必要）
npx @tailwindcss/upgrade

このツールは、依存パッケージの更新・@tailwind ディレクティブの置換・tailwind.config.js のCSSへの移行・リネームされたクラスの一括置換までまとめて行います。必ず新しいGitブランチで実行し、差分（diff）を目視で確認してください。自動変換で拾いきれなかった箇所が、これから説明する「手で直す」対象です。

それでは、ツールでも崩れが残りやすい代表的なポイントを、症状別に見ていきます。

① ボーダーの色が変わった（gray-200 → currentColor）

移行後に一番よく報告されるのがこれです。v3 では border だけ書けば、デフォルトで薄いグレー（gray-200）のボーダーが引かれていました。v4 では、このデフォルト色が currentColor（＝テキスト色）に変更されました。ブラウザ本来の挙動に寄せ、思い込みを減らすための変更です。

そのため、色を指定せず border だけ書いていた箇所は、テキスト色（多くは黒に近い色）でボーダーが引かれて濃く見えるようになります。対処は2通りです。

対処A（推奨）：ボーダー色を明示する。 一番正しい直し方です。ボーダーを引く箇所で色クラスも一緒に指定します。

<!-- v3（暗黙で gray-200 が付いていた） -->
<div class="border p-4">...</div>

<!-- v4（色を明示する） -->
<div class="border border-gray-200 p-4">...</div>

対処B（応急処置）：v3 の挙動を全体に復元する。 該当箇所が多すぎてすぐ直せない場合は、エントリCSSにベーススタイルを足して「色未指定なら gray-200」を復活させられます。

@import "tailwindcss";

@layer base {
  *,
  ::after,
  ::before,
  ::backdrop,
  ::file-selector-button {
    border-color: var(--color-gray-200, currentColor);
  }
}

応急処置は便利ですが、v4 本来の設計に反する「グローバルな上書き」です。時間ができたら対処A（色を明示）へ寄せていくのがおすすめです。なお divide-*（要素間の区切り線）も同じくデフォルトが currentColor になっているので、同様に色指定を足してください。

② フォーカスのリングが細くなった・色が変わった

フォームの入力欄やボタンで ring を使ってフォーカス枠を出していた方は、移行後に「枠が細くなった」「青だったのが黒っぽくなった」と気づくはずです。v4 では、他のユーティリティ（border-* / outline-*）とそろえるために、ring の仕様が次のように変わりました。

• 幅：3px → 1px
• デフォルト色：blue-500 → currentColor

v3 と同じ「3px の枠」に戻したいだけなら、ring を ring-3 に置き換えます。色も v3 の青に戻したい場合は色クラスを添えます。

<!-- v3 の見た目（3px・青） -->
<button class="ring">...</button>

<!-- v4 で同じ見た目に戻す -->
<button class="ring-3 ring-blue-500">...</button>

「細くなっただけで色は気にならない」なら ring-3 だけでOKです。逆に、この機会に 1px の控えめなリングへ寄せるなら、そのまま ring を使い続けても構いません。デザイン方針しだいです。

③ 影・角丸・outline のクラス名が総入れ替えされた

v4 では、すべてのユーティリティに大きさの接尾辞を付けてそろえる方針になり、影・角丸・ぼかしのスケール名が1段ずつずれました。名前は同じでも中身（サイズ）が変わっているため、「なんとなく影や角丸が違う」という微妙な崩れを生みます。

ポイントは、接尾辞なしの shadow / rounded / blur が、それぞれ -sm 付きの意味に変わったことです。つまり v3 の shadow は v4 の shadow-sm に相当します。自動アップグレードツールはこの置換もやってくれますが、文字列連結でクラス名を組み立てている箇所（例：`shadow-${size}`）は拾えないので、手で確認してください。

もう一つの落とし穴が outline-none です。v3 の outline-none は、実は「透明な outline を引く」（アクセシビリティ用）挙動でした。v4 ではこれが outline-hidden に改名され、新しい outline-none は文字どおり outline-style: none を意味します。フォーカス時の枠消しに outline-none を使っていた箇所は、意図が変わっていないか確認しましょう。

<!-- v3 の outline-none 相当（透明outlineを残す） -->
<input class="outline-hidden" />

<!-- 本当に outline を消したい場合（アクセシビリティ注意） -->
<input class="outline-none" />

④ ビルドが通らない・@tailwind が効かない

スタイル以前に「ビルドでエラーが出る」「CSSがまったく生成されない」場合は、エントリCSSの記法とPostCSSプラグインの構成という2つの土台が変わったのが原因です。

@tailwind ディレクティブは廃止された

v3 で書いていた3行の @tailwind は、v4 では1行の @import に置き換わりました。

/* v3 */
@tailwind base;
@tailwind components;
@tailwind utilities;

/* v4 */
@import "tailwindcss";

PostCSSプラグインが別パッケージに分離した

PostCSS 経由で使っている場合、次のエラーに出会うことがあります。

It looks like you're trying to use `tailwindcss` directly as a PostCSS plugin.
The PostCSS plugin has moved to a separate package...

これは、PostCSS プラグインが tailwindcss 本体から @tailwindcss/postcss という別パッケージに切り出されたためです。パッケージを追加し、postcss.config の記述を差し替えます。

npm install tailwindcss @tailwindcss/postcss postcss

// v3: postcss.config.js
export default {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  },
};

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

v4 では @import の解決とベンダープレフィックス付けが自動になったため、postcss-import と autoprefixer は不要になります。残しておくと二重処理で崩れる場合があるので、削除してしまって構いません。なお、Vite を使っているなら PostCSS すら不要で、@tailwindcss/vite プラグインを使うのが公式推奨です。

ちなみに Rails で tailwindcss-rails gem を使っている場合は、この PostCSS 周りを意識する必要はありません（Node.js 不要のスタンドアロンCLIで動くため）。Rails への導入手順は RailsにTailwind CSS v4を導入する方法 にまとめています。

⑤ tailwind.config.js の設定が反映されない

「カスタムカラーやフォントの設定が全部消えた」ように見えるのも定番です。v4 は設定をCSSファーストに切り替えたため、tailwind.config.js は自動では読み込まれなくなりました。テーマの拡張は、CSS内の @theme ブロックで定義します。

@import "tailwindcss";

/* v3 の theme.extend.colors に相当 */
@theme {
  --color-brand: #4f46e5;
  --font-display: "Inter", sans-serif;
}

こう定義すると bg-brand や font-display がそのまま使えます。とはいえ「今すぐ全部CSSに書き直す時間はない」という場合もありますよね。その時は、既存のJS設定を明示的に読み込む @config ディレクティブで当面しのげます。

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

パスは、CSSファイルから見た tailwind.config.js への相対パスです。まずは @config で動く状態にしてから、少しずつ @theme へ移していくと、移行の負担を分割できます。

移行前に知っておきたい注意点

• 対応ブラウザが変わった：v4 は Safari 16.4 / Chrome 111 / Firefox 128 以降が前提です。古いブラウザを本気でサポートする案件では、v3 のまま据え置く判断も十分アリです。
• Node.js 20 以上が必要：アップグレードツール（npx @tailwindcss/upgrade）は Node 20+ を要求します。CIやローカルのNodeバージョンを先に確認しましょう。
• 必ずブランチを分けて差分を確認：自動変換は強力ですが万能ではありません。Gitで差分を見て、意図しない置換がないかを目視でチェックしてください。

なお、v4 移行とは別に「タッチ対応PCで hover: が効かなくなった」という現象もあります。これは hover の出力仕様がメディアクエリ前提に変わったのが原因で、別記事の Tailwind CSSでhoverが効かない原因と対処 で扱っています。あわせて確認しておくと、移行後のトラブルを一気に潰せます。

まとめ

Tailwind CSS v3→v4 の「効かない・崩れる」は、原因さえ分かれば怖くありません。要点はこの4つです。

• まず npx @tailwindcss/upgrade を新しいブランチで実行し、差分を確認する
• 色まわり（ボーダー・リングの currentColor 化）は色を明示して直す
• 影・角丸・outline-none のリネームを機械的に置換する
• ビルドは @import "tailwindcss" ＋ @tailwindcss/postcss、設定は @theme（当面は @config）に寄せる

移行が落ち着いたら、v4 の新しい書き方でUIを組み直す段階です。ユーティリティクラスの基本からレイアウトの作り方までは Tailwind CSSの使い方【初心者向け】 に、親要素のホバーで子要素を動かすといった一歩進んだテクニックは Tailwind CSSのgroup-hoverの使い方 にまとめています。v4 の快適さを、ぜひ実戦で味わってください。

参考リンク

• Upgrade guide（Tailwind CSS 公式）
• Tailwind CSS v4.0（公式ブログ）

スポンサーリンク