Tailwind CSS 3.4 のPostCSS構成が4.3で動かないときの直し方
Tailwind CSS 3.4.19 のPostCSS構成を4.3.5へ上げると、プラグインエラーに加え、ユーティリティ欠落と見た目の変化が起きました。同じ最小プロジェクトで出力CSSを比較しながら、4箇所の修正と確認手順をまとめます。
- tailwindcss を4系に上げたら、PostCSSのビルドがエラーで止まった
- ビルドは通るのに、text-brand や shadow-sm が出力CSSから消えた
- JS設定のカスタムカラーや、ring・shadow・borderの見た目を維持したい
対象読者: Tailwind CSS 3.4 をPostCSSで運用していて、4系へ移行したい人です。
前提知識: npmとPostCSSの基本操作、Tailwindのユーティリティクラスが分かることです。
結論
PostCSS構成ではプラグイン・CSSの読み込み・JS設定・クラス名の4箇所を直します。最後に出力CSSを比較すれば、ビルドが通るだけでは見つからない変更も確認できます。
npm install tailwindcss@4.3.5 @tailwindcss/postcss@4.3.5
npm run build
# 実行結果(修正完了後)
# [v4.3.5 + fixed classes] build exit=0
# fixed .border-gray-200: True
# fixed .shadow-xs: True
# fixed .text-brand: True
# fixed .ring-3: True
# fixed .ring-blue-500: True
公式は新しいブランチで npx @tailwindcss/upgrade を実行する方法を推奨しています。今回は変更を1つずつ確かめるため、公式アップグレードガイドの手動移行手順で進めました。
| 箇所 | 起きたこと | 直し方 |
|---|---|---|
| PostCSS | v4にした瞬間ビルドが停止 | @tailwindcss/postcss を使う |
| @tailwind | 終了コード0でもCSSが欠落 | @import “tailwindcss” にする |
| JS設定 | text-brand が消える | @config で明示する |
| クラス | 影・リング・枠線の見た目が変わる | shadow-xs・ring-3・色指定を使う |
移行前の構成と確認方法
移行前は Tailwind CSS 3.4.19・PostCSS・autoprefixer の構成です。カスタムカラー text-brand と、border・shadow-sm・ring を付けた1つのボタンをビルド対象にしました。
// tailwind.config.mjs
export default {
content: ["./index.html"],
theme: {
extend: {
colors: {
brand: "#123456",
},
},
},
};
// 実行結果(Tailwind CSS 3.4.19)
// [v3.4.19] build exit=0
// v3 text-brand: True
各段階で npm run build を実行し、出力CSSに目的のセレクタがあるかを調べました。shadow と ring は宣言値まで比較しています。
1. PostCSSプラグインの分離でビルドが止まった
v4では tailwindcss をPostCSSプラグインとして直接指定できません。専用パッケージへの移行が必要です。
npm install tailwindcss@4.3.5
npm run build
# 実行結果
# Error: It looks like you're trying to use `tailwindcss` directly as a PostCSS plugin. The PostCSS plugin has moved to a separate package, so to continue using Tailwind CSS with PostCSS you'll need to install `@tailwindcss/postcss` and update your PostCSS configuration.
@tailwindcss/postcss をインストールし、設定のキーごと置き換えます。
// postcss.config.mjs
export default {
plugins: {
"@tailwindcss/postcss": {},
},
};
// 実行結果
// [v4.3.5 + fixed classes] build exit=0
Tailwindのためだけに使っていた postcss-import と autoprefixer は外せます。v4ではimportの展開とvendor prefix付与をTailwind側が処理するためです。
2. @tailwindのままだとビルド成功なのにCSSが欠けた
最初のエラーを直しただけでは移行は終わりません。v3のディレクティブを残したまま4.3.5でビルドしたところ、終了コードは0なのに2つのクラスが出力されませんでした。
/* src/input.css(移行前) */
@tailwind base;
@tailwind components;
@tailwind utilities;
/* 実行結果 */
/* [v4.3.5 + old @tailwind] build exit=0 */
/* old @tailwind text-brand: False / shadow-sm: False */
公式も @tailwind ディレクティブは削除されたと案内しています。通常のCSS import 1行へ置き換えます。
@import "tailwindcss";
@config "../tailwind.config.mjs";
/* 実行結果 */
/* [v4.3.5 + @config] build exit=0 */
/* @config text-brand: True */
「エラーが無い」を確認先にすると取りこぼします。移行中は主要なクラスが出力CSSに残るかまで見るのが確実です。
3. tailwind.config.mjsが自動で読まれずtext-brandが消えた
@import だけにした段階では、text-brand が出力されませんでした。v4はソースファイルを自動検出しますが、JavaScriptの設定ファイルまでは自動で読み込みません。
@import "tailwindcss";
/* 実行結果 */
/* [v4.3.5 + @import only] build exit=0 */
/* @import only text-brand: False */
既存のJS設定を残すなら、公式のJavaScript config移行説明にある通り @config が必要です。今回はinput.cssから1つ上の階層を指定しました。
なお、v4の自動検出はテンプレート側の話です。公式のソース検出ドキュメントでは、.gitignore の対象やバイナリファイルは除外すると説明されています。
4. shadow・ring・borderの既定値が変わった
同じクラスが残っていても、見た目は元に戻りません。特に shadow-sm はv4で別の段階を指すため、生成CSSを比較すると差が出ます。
/* v3.4.19の出力(宣言を抜粋) */
.shadow-sm {
--tw-shadow: 0 1px 2px 0 rgb(0 0 0 / 0.05);
}
/* v4.3.5の出力(宣言を抜粋) */
.shadow-sm {
--tw-shadow: 0 1px 3px 0 var(--tw-shadow-color, rgb(0 0 0 / 0.1)), 0 1px 2px -1px var(--tw-shadow-color, rgb(0 0 0 / 0.1));
}
ring も実測では3pxから1pxに変わり、色のフォールバックは currentcolor になりました。border の既定色も v3のgray-200から currentColor に変わっています。
v3の見た目に寄せるため、クラスを次のように変更しました。
v3: border p-4 shadow-sm text-brand ring
v4: border border-gray-200 p-4 shadow-xs text-brand ring-3 ring-blue-500
実行結果
fixed .border-gray-200: True
fixed .shadow-xs: True
fixed .text-brand: True
fixed .ring-3: True
fixed .ring-blue-500: True
変更点の全一覧は公式の Changes from v3にあります。今回の3つ以外もクラス名の一覧と表示を確認しておきます。
つまずきポイント
- アップグレードツールにはNode.js 20以上が必要です。今回はNode.js 24.16.0で実行しました。
- v4の対象はSafari 16.4・Chrome 111・Firefox 128以降です。古いブラウザ対応が必要ならv3.4を維持します。
- ビルド成功と見た目の維持は別です。カスタムカラー・shadow・ring・borderは出力CSSを比較します。
ブラウザ要件も公式ガイドのBrowser requirementsに明記されています。ここだけ後から気づくと、移行自体をやり直す判断になります。
検証環境
| OS | Windows 11 (build 10.0.26200) |
|---|---|
| CPU | AMD Ryzen 9 PRO 8945HS w/ Radeon 780M Graphics |
| メモリ | 28GB |
| 言語/ツール | Tailwind CSS 3.4.19 / Tailwind CSS 4.3.5 + @tailwindcss/postcss 4.3.5(npmで一時インストール) / Node.js 24.16.0 |
| 使用コマンド | python migration_check.py(PostCSSビルドと出力CSSの比較) |
| 測定日 | 2026-11-17 |
上記の環境で実際に実行して確認した結果です。環境が異なる場合は挙動が変わることがあります。

まとめ
Tailwind CSS 3.4から4.3への移行では、PostCSS周りを直した後に、JS設定とクラスの差分を確認します。今回は4箇所の修正でカスタムカラーを復元し、影・リング・枠線にv3相当の指定を戻せました。
自動ツールを使う場合も、差分確認の観点は同じです。主要コンポーネントのクラスと生成CSSを残しておくと、後から原因を追いやすいですよ。
参考
- Tailwind CSS 公式 Upgrade guide
- Tailwind CSS v4.0 公式リリース記事
- Tailwind CSS 公式 Detecting classes in source files
- tailwindlabs/tailwindcss v4.3.5 リリースノート
あわせて読みたい
- Tailwind CSS v4 セットアップ完全ガイド|Vite + @theme
- 【Tailwind CSS v4】Cannot apply unknown utility class の直し方
- 【Vite】Vite 8 移行ガイド2026 — Rolldown 統合で壊れる設定
この記事を書いた人: Kurosaki.Ren。記事のコードは隔離した環境で実行してから掲載しています。詳しいプロフィールは著者プロフィールページへどうぞ。
【広告】このサイトはConoHa WINGで運営しています。安定した高速サーバーで快適にブログを書けています。いつもありがとう!!![]()

コメント