🎨

【Tailwind CSS】v3→v4 への移行でスタイルが効かない時の解決法

に公開
CSS
Tailwind CSS
tech

はじめに

Tailwind CSS を v3 から v4 にアップデートしたところ、画面のスタイルがまったく効かなくなるトラブルに遭遇しました。
この記事では、Tailwind CSS v3 と v4 の概要や運用方針を含め、私が直面した実際の問題と解決方法をまとめます。

対象者

  • Tailwind CSS v4 を使っていて CSS が効かなくなった人
  • v3 からアップデートしたがトラブルに遭遇している人
  • globals.css の扱い方やエラーログで悩んでいる人

Tailwind CSS v3 と v4 の概要とメリット

現在(2025年9月時点)では、新規プロジェクトでは v4 の採用が推奨されつつあります。一方で、既存の大規模プロジェクトや古いブラウザ対応が必要な環境では v3 を継続利用しているケースも多く、両者が併存しているのが現状です。

v3 は、後方互換性が高く、既存環境で安定動作しやすいです。
v4 は、ビルド速度や拡張性に優れ、今後の長期メンテナンスはこちらが中心になります。

v3 の特徴

  • @tailwind base; @tailwind components; @tailwind utilities; の3ディレクティブで利用する従来方式
  • 既存プロジェクトに導入しやすい
  • 豊富なユーティリティクラスを提供し、学習コストが比較的低い
  • 古いブラウザサポートが広い

https://v3.tailwindcss.com/docs/installation

v4 の特徴

  • 記法が刷新され、@import "tailwindcss"; と @source でクラス検出を行う新方式に
  • ビルドがよりシンプルに
  • 動的クラス利用時は @source inline や safelist などを明示する必要がある（自動検出がより厳格化）
  • 対応ブラウザが比較的新しく（例: Chrome 111+, Safari 16.4+ など）、モダン環境向けに最適化

https://tailwindcss.com/blog/tailwindcss-v4

おすすめの運用方針

  • 短期的に「まずは動かす」なら v3 記法を残して後方互換を利用（ただし将来削除される可能性あり）
  • 中期〜長期的には v4 の @import + @source に統一して運用するのが望ましい
  • 動的クラスが必要な場合は、@source inline() や safelist を利用して確実に検出させる
  • チーム開発の場合は、v4 ベースで構成を統一しておくとトラブルを避けやすい

v3 から v4 へのアップグレード方法

前提

以下の前提を考慮して実行してください。

  • Node.js 20 以上が必須
  • 最新のブラウザ向けに設計されており、ブラウザの要件は、Safari 16.4、Chrome 111、Firefox 128 を対象としています。
  • 新しいブランチを切って実行し、差分を確認すること
  • 自動変換後も必ずテストして挙動を検証すること

アップグレードガイドの活用

Tailwind CSS 公式のアップグレードガイドに沿って作業すると安全に移行できます。基本的な流れは以下の通りです。

https://tailwindcss.com/docs/upgrade-guide

  1. アップグレードツールを実行
    基本的には以下のコマンドで依存関係の更新や設定ファイルの移行など、必要な作業の多くが自動で適用されます。
npx @tailwindcss/upgrade
  1. globals.css を v4 記法に書き換える
@import "tailwindcss";
@source "./**/*.{ts,tsx}";
  1. 手動調整
  • globals.css の import 部分や v3 記法削除
  • プロジェクト固有の PostCSS 設定や Vite 設定の見直し
  • safelist や動的クラスに関する記述

発生した問題

Tailwind v3 のときは以下の記述で問題なく動いていました。

/* globals.css (v3) */
@tailwind base;
@tailwind components;
@tailwind utilities;

ところが v4 に合わせて、次のように書き換えた途端 UI が崩壊しました。

/* globals.css (v4 移行時) */
@import "tailwindcss";
@source "./**/*.{ts,tsx}";

症状としては、以下の現象がおきました。

  • すべてのスタイルが適用されずプレーンなHTML表示に
  • ビルドログに / _next/static/css/app/layout.css 404 が出る
  • globals.css を import しても効かない

解決方法

原因は「v3 と v4 のディレクティブが混在していたこと」と「誤った場所で globals.css を import していたこと」でした。対応は次の2パターンです。

解決策1（暫定）

v3 のディレクティブを残す。Tailwind v4 でも @tailwind base; 記法は後方互換で動作するため、すぐに動かしたいならこの方法が有効です。ただし将来的に削除される可能性があるため注意。

解決策2（推奨）

v4 形式に統一する。

  • globals.css を以下に修正

    @import "tailwindcss";
@source "./**/*.{ts,tsx}";

  • @tailwind base; など v3 記法は削除

  • globals.css はプロジェクトのルートで1回だけ import

  • postcss.config.js を v4 用に整理

  • 動的クラスが必要なら safelist または @source inline() を適切に利用

学び・まとめ

今回の移行で得たポイントは以下の通りです。

  • Tailwind v4 は v3 記法も一部後方互換で動作するが、将来削除される可能性があるため早めに移行すべき
  • CSS 404 エラーは「誤った場所で globals.css を import」していたことが原因になり得る
  • 移行時は globals.css 冒頭 / ルートでの import / postcss.config.js の3点セットを必ず確認すること
  • 動的クラスは v4 では厳格に扱われるため、@source inline() や safelist を利用する
  • 運用方針としては、短期的には v3 後方互換で対応しつつ、中長期的には v4 に統一していくのが安全

おわりに

Tailwind CSS v4 への移行は、一見すると単純なアップデート作業に見えますが、記法の違いやグローバル CSS の import 制約が絡むと「CSS が効かない」という大きなトラブルに発展します。私自身も最初は原因がわからず数時間ハマりましたが、整理してみるとシンプルな落とし穴でした。

今後は v4 ベースでの運用を統一しつつ、過渡期には v3 記法の後方互換を活かす二段構えで進めていくのが安心です。この記事が同じように悩んでいる方の助けになれば嬉しいです。

GitHubで編集を提案

Discussion