Vite で開発を進めていると、スタイルを変更したのにブラウザに反映されない……そんな経験はありませんか？

CSS の Hot Module Replacement（HMR）が正常に動作しないと、開発効率が大幅に低下してしまいます。特に PostCSS や CSS Modules を利用している環境では、設定の不備やキャッシュの問題で HMR が機能しなくなることがあるのです。

本記事では、Vite における CSS HMR のトラブルシューティングに焦点を当て、PostCSS、CSS Modules、キャッシュという 3 つの要素から問題を切り分ける方法を詳しく解説します。実際のエラーコードやその解決方法を含めて、段階的に問題を特定し解決できるようになりましょう。

背景

Vite における HMR の仕組み

Vite は開発サーバーとして優れたパフォーマンスを発揮しますが、その中核を担うのが HMR の仕組みです。

HMR は、ファイルが変更されたときに、ブラウザをリロードすることなく、変更された部分だけを即座に差し替える機能です。CSS の場合、変更されたスタイルシートが自動的にブラウザに送信され、リアルタイムで反映されます。

Vite の HMR では以下の流れで CSS の更新が処理されます。

mermaidCopy codeflowchart TD
  A["開発者が CSS を編集"] --> B["Vite がファイル変更を検知"]
  B --> C{"PostCSS 処理が<br/>必要か？"}
  C -->|Yes| D["PostCSS でトランスパイル"]
  C -->|No| E["CSS をそのまま処理"]
  D --> F["CSS Modules の<br/>変換処理"]
  E --> F
  F --> G["WebSocket 経由で<br/>ブラウザに送信"]
  G --> H["ブラウザが<br/>スタイルを更新"]

この仕組みにより、ミリ秒単位でのスタイル反映が実現されています。

PostCSS と CSS Modules の役割

PostCSS は CSS を変換するためのツールで、Autoprefixer や Tailwind CSS など多くのプラグインが利用できます。一方、CSS Modules は CSS のクラス名をスコープ化し、コンポーネント間のスタイル干渉を防ぐ技術です。

これらは開発を便利にする反面、設定ミスや互換性の問題により HMR が正常に動作しなくなる原因となることもあります。

以下の表は、それぞれの技術が HMR に与える影響をまとめたものです。

#	技術	HMR への影響	主な問題点
1	PostCSS	変換処理が挟まる	プラグインの設定ミス、処理エラー
2	CSS Modules	クラス名のハッシュ化	インポート方法の誤り、型定義の不一致
3	キャッシュ	ビルド結果の保存	古いキャッシュの残存、キャッシュディレクトリの権限

課題

CSS HMR が反映されない典型的な症状

CSS の HMR が正しく動作しない場合、以下のような症状が現れます。

症状 1：ファイルを保存しても何も起きない CSS ファイルを編集して保存しても、ブラウザに何の変化も現れません。開発サーバーのログにもエラーは表示されないため、原因の特定が難しいケースです。

症状 2：フルリロードになってしまう CSS の変更は反映されるものの、HMR ではなくページ全体がリロードされてしまいます。これではフォームの入力内容や状態が失われてしまいますね。

症状 3：エラーメッセージが表示される 開発サーバーのターミナルやブラウザのコンソールに PostCSS 関連のエラーが表示され、HMR が停止してしまいます。

mermaidCopy codestateDiagram-v2
  [*] --> CSSEdit: CSS を編集
  CSSEdit --> Detection: Vite が検知
  Detection --> Processing: 処理開始

  Processing --> Error1: エラー発生
  Processing --> Error2: キャッシュ問題
  Processing --> Success: 正常処理

  Error1 --> NoUpdate: 画面に反映されない
  Error2 --> NoUpdate
  Success --> HMRUpdate: HMR 更新
  Success --> FullReload: フルリロード

  NoUpdate --> [*]
  HMRUpdate --> [*]
  FullReload --> [*]

問題の根本原因

これらの症状の背後には、主に 3 つの原因が潜んでいます。

原因 1：PostCSS の設定不備 postcss.config.js の設定ミスや、プラグインのバージョン不一致によって、CSS の変換処理が失敗し HMR が停止します。

原因 2：CSS Modules の誤った使い方 インポート方法の誤りや、型定義ファイルの不整合により、Vite が CSS Modules を正しく認識できないケースがあります。

原因 3：キャッシュの問題 .vite ディレクトリや node_modules​/​.cache に保存された古いビルド結果が残り続けることで、最新の CSS が反映されないことがあります。

これらの原因を正確に切り分け、適切な対処を行うことが重要です。

解決策

チェックリスト 1：PostCSS の設定を確認する

PostCSS の設定が正しく行われているか、段階的に確認していきましょう。

ステップ 1：postcss.config.js の存在確認

まず、プロジェクトルートに postcss.config.js が存在するか確認します。

bashCopy codels -la postcss.config.js

ファイルが存在しない場合、Vite はデフォルトの PostCSS 設定を使用しますが、プラグインを利用している場合は明示的な設定が必要です。

ステップ 2：基本的な PostCSS 設定の作成

以下は、最小限の PostCSS 設定ファイルの例です。

javascriptCopy code// postcss.config.js
export default {
  plugins: {
    autoprefixer: {},
  },
};

この設定では、Autoprefixer プラグインのみを有効にしています。シンプルな構成から始めることで、問題の切り分けがしやすくなりますね。

ステップ 3：プラグインの依存関係を確認

PostCSS プラグインが正しくインストールされているか確認しましょう。

bashCopy codeyarn list --pattern "postcss|autoprefixer"

プラグインがインストールされていない場合は、以下のコマンドでインストールします。

bashCopy codeyarn add -D postcss autoprefixer

ステップ 4：プラグインのバージョン互換性チェック

PostCSS 8 系を使用している場合、一部のプラグインは互換性がない可能性があります。

javascriptCopy code// postcss.config.js
// PostCSS 8 系での推奨設定
export default {
  plugins: {
    'postcss-import': {},
    'tailwindcss/nesting': {},
    tailwindcss: {},
    autoprefixer: {},
  },
};

プラグインは上から順に適用されるため、依存関係のある順序で配置することが重要です。特に postcss-import は最初に、autoprefixer は最後に配置するのがベストプラクティスとなります。

ステップ 5：エラーログの確認

PostCSS の処理エラーが発生している場合、ターミナルに以下のようなエラーが表示されます。

textCopy codeError: PostCSS plugin postcss-preset-env requires PostCSS 8.

このエラーは、プラグインが要求する PostCSS のバージョンと、実際にインストールされているバージョンが一致していないことを示しています。

エラーコード: Error: PostCSS plugin requires PostCSS 8

発生条件: PostCSS 7 系がインストールされている状態で、PostCSS 8 専用のプラグインを使用した場合

解決方法:

1. PostCSS のバージョンを確認する：yarn list postcss
2. PostCSS 8 にアップグレードする：yarn add -D postcss@latest
3. すべてのプラグインを最新版に更新する：yarn upgrade --latest --pattern "postcss-*"
4. 開発サーバーを再起動する：yarn dev

チェックリスト 2：CSS Modules の設定を確認する

CSS Modules を使用している場合、インポート方法や設定を正しく行う必要があります。

ステップ 1：正しいインポート方法の確認

CSS Modules ファイルは .module.css という拡張子を持ち、特別な方法でインポートする必要があります。

typescriptCopy code// ❌ 誤った方法
import './styles.module.css';

この方法では、CSS Modules として認識されず、クラス名のハッシュ化が行われません。

typescriptCopy code// ✅ 正しい方法
import styles from './styles.module.css';

このように、import 文で default エクスポートとして受け取ることで、CSS Modules が正しく機能します。

ステップ 2：型定義ファイルの確認

TypeScript を使用している場合、CSS Modules の型定義が必要です。

typescriptCopy code// vite-env.d.ts
/// <reference types="vite/client" />

// CSS Modules の型定義を追加
declare module '*.module.css' {
  const classes: { readonly [key: string]: string };
  export default classes;
}

この型定義により、TypeScript が CSS Modules のインポートを正しく認識できるようになります。

ステップ 3：Vite の CSS Modules 設定

vite.config.ts で CSS Modules の詳細な動作を制御できます。

typescriptCopy code// vite.config.ts
import { defineConfig } from 'vite';

export default defineConfig({
  css: {
    modules: {
      // クラス名の生成パターン
      generateScopedName:
        '[name]__[local]___[hash:base64:5]',
      // ハッシュアルゴリズム
      hashPrefix: 'prefix',
    },
  },
});

この設定では、生成されるクラス名のフォーマットを細かく制御しています。開発環境では可読性の高い名前、本番環境では短い名前にすることも可能です。

ステップ 4：グローバルスタイルとの混在確認

CSS Modules ファイル内でグローバルスタイルを定義する場合は、:global セレクタを使用します。

cssCopy code/* styles.module.css */

/* ローカルスコープ（デフォルト） */
.button {
  padding: 10px 20px;
}

/* グローバルスコープ */
:global(.global-button) {
  margin: 10px;
}

グローバルスタイルが多い場合は、別ファイルに分離することをおすすめします。

ステップ 5：CSS Modules が反映されない場合のエラー確認

CSS Modules のクラスが undefined になる場合、以下のエラーが発生します。

textCopy codeTypeError: Cannot read properties of undefined (reading 'button')

エラーコード: TypeError: Cannot read properties of undefined

発生条件: CSS Modules を正しくインポートしていない、または型定義が不足している場合

解決方法:

1. インポート文を確認：import styles from '.​/​styles.module.css' の形式になっているか
2. ファイル拡張子を確認：.module.css になっているか
3. 型定義ファイルを確認：vite-env.d.ts に CSS Modules の型定義があるか
4. 開発サーバーを再起動：Ctrl+C で停止後、yarn dev で再起動

チェックリスト 3：キャッシュをクリアする

キャッシュの問題は、設定が正しくても発生することがあります。段階的にクリアしていきましょう。

ステップ 1：ブラウザのキャッシュをクリア

まずは最も基本的な、ブラウザのキャッシュクリアから始めます。

Chrome の場合、以下の手順で実行できます：

1. DevTools を開く（F12 または Cmd+Option+I）
2. Network タブを開く
3. 「Disable cache」にチェックを入れる
4. ページをリロード（Cmd+Shift+R）

開発中は DevTools を開いた状態で作業することで、常にキャッシュを無効化できます。

ステップ 2：Vite のキャッシュディレクトリを削除

Vite は .vite ディレクトリにビルドキャッシュを保存しています。

bashCopy coderm -rf .vite

このディレクトリを削除することで、Vite は次回起動時に新しいキャッシュを生成します。

ステップ 3：node_modules のキャッシュを削除

依存パッケージのキャッシュが問題を引き起こすこともあります。

bashCopy coderm -rf node_modules/.cache

特に PostCSS や CSS 処理に関連するパッケージのキャッシュは、ここに保存されることが多いです。

ステップ 4：yarn のキャッシュをクリア

Yarn 自体のキャッシュも、まれに問題の原因となります。

bashCopy codeyarn cache clean

このコマンドで、Yarn がダウンロードしたパッケージのキャッシュがすべて削除されます。

ステップ 5：完全なクリーンインストール

すべてのキャッシュを削除し、依存関係を再インストールする完全なクリーンアップです。

bashCopy code# すべてのキャッシュとインストール済みパッケージを削除
rm -rf node_modules .vite node_modules/.cache

# yarn.lock は残す（推奨）
# 依存関係を再インストール
yarn install

# 開発サーバーを起動
yarn dev

この手順により、環境が完全にクリーンな状態に戻ります。時間はかかりますが、原因不明の問題を解決する最終手段として有効です。

ステップ 6：キャッシュ関連の権限エラー対応

キャッシュディレクトリの権限エラーが発生する場合があります。

textCopy codeError: EACCES: permission denied, mkdir '/path/to/project/.vite'

エラーコード: EACCES: permission denied

発生条件: キャッシュディレクトリの書き込み権限がない場合

解決方法:

1. ディレクトリの権限を確認：ls -la .vite
2. 権限を修正：chmod -R 755 .vite
3. 所有者を確認：ls -la .vite
4. 必要に応じて所有者を変更：sudo chown -R $USER:$USER .vite
5. キャッシュディレクトリを削除して再生成：rm -rf .vite && yarn dev

以下の図は、キャッシュクリアの優先順位と効果範囲を示しています。

mermaidCopy codeflowchart TD
  Start["キャッシュ問題の発生"] --> Level1{"軽度の問題？"}

  Level1 -->|Yes| Browser["ブラウザキャッシュ<br/>をクリア"]
  Level1 -->|No| Level2{"中程度の問題？"}

  Browser --> Check1{"解決した？"}
  Check1 -->|Yes| End["完了"]
  Check1 -->|No| Level2

  Level2 -->|Yes| ViteCache[".vite ディレクトリ<br/>を削除"]
  Level2 -->|No| Level3{"重度の問題？"}

  ViteCache --> Check2{"解決した？"}
  Check2 -->|Yes| End
  Check2 -->|No| Level3

  Level3 -->|Yes| NodeCache["node_modules/.cache<br/>を削除"]
  Level3 -->|No| FullClean["完全クリーン<br/>インストール"]

  NodeCache --> Check3{"解決した？"}
  Check3 -->|Yes| End
  Check3 -->|No| FullClean

  FullClean --> End

統合的なトラブルシューティングフロー

これまでのチェックリストを統合した、問題解決のフローチャートです。

mermaidCopy codeflowchart TD
  Problem["CSS HMR が<br/>反映されない"] --> Symptom{"症状の確認"}

  Symptom -->|エラーあり| PostCSSCheck["PostCSS 設定を<br/>確認"]
  Symptom -->|エラーなし| CSSModuleCheck["CSS Modules<br/>を確認"]

  PostCSSCheck --> ConfigExists{"postcss.config.js<br/>が存在？"}
  ConfigExists -->|No| CreateConfig["設定ファイル<br/>を作成"]
  ConfigExists -->|Yes| PluginCheck["プラグイン<br/>確認"]

  CreateConfig --> Restart1["サーバー再起動"]
  PluginCheck --> VersionCheck["バージョン<br/>確認"]
  VersionCheck --> Restart1

  CSSModuleCheck --> ImportCheck{"インポート方法<br/>は正しい？"}
  ImportCheck -->|No| FixImport["インポート文<br/>修正"]
  ImportCheck -->|Yes| TypeCheck["型定義確認"]

  FixImport --> Restart2["サーバー再起動"]
  TypeCheck --> Restart2

  Restart1 --> Resolved1{"解決した？"}
  Restart2 --> Resolved2{"解決した？"}

  Resolved1 -->|Yes| Success["完了"]
  Resolved1 -->|No| CacheClean
  Resolved2 -->|Yes| Success
  Resolved2 -->|No| CacheClean

  CacheClean["キャッシュ<br/>クリア"] --> BrowserCache["ブラウザ<br/>キャッシュ"]
  BrowserCache --> ViteDir[".vite 削除"]
  ViteDir --> NodeModulesCache["node_modules<br/>/.cache 削除"]
  NodeModulesCache --> FinalCheck{"解決した？"}

  FinalCheck -->|Yes| Success
  FinalCheck -->|No| FullReset["完全クリーン<br/>インストール"]
  FullReset --> Success

図で理解できる要点:

• まずエラーの有無で PostCSS または CSS Modules の問題を切り分ける
• 各チェックポイントでサーバー再起動を挟むことが重要
• 設定で解決しない場合は、段階的にキャッシュをクリアする

具体例

実例 1：Tailwind CSS の PostCSS 設定エラー

Tailwind CSS を使用しているプロジェクトで、CSS の変更が反映されなくなった事例です。

問題の発生

開発者が Tailwind CSS のクラスを追加しても、ブラウザに反映されない状況が発生しました。ターミナルには以下のエラーが表示されています。

textCopy codeError: PostCSS plugin tailwindcss requires PostCSS 8.
Migration guide for end-users:
https://github.com/postcss/postcss/wiki/PostCSS-8-for-end-users

このエラーは、PostCSS 7 系がインストールされているのに、Tailwind CSS 3.x（PostCSS 8 が必要）を使用していることを示しています。

原因の特定

パッケージのバージョンを確認してみます。

bashCopy codeyarn list postcss

結果：

textCopy code└─ postcss@7.0.39

PostCSS が 7 系のままであることが確認できました。

解決手順

手順 1：PostCSS を 8 系にアップグレード

bashCopy codeyarn add -D postcss@latest autoprefixer@latest

このコマンドで、PostCSS と関連プラグインを最新版に更新します。

手順 2：Tailwind CSS の依存関係を確認

bashCopy codeyarn add -D tailwindcss@latest

Tailwind CSS も最新版に更新することで、互換性を確保します。

手順 3：PostCSS 設定ファイルを更新

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

シンプルな設定で、Tailwind CSS と Autoprefixer のみを有効化します。

手順 4：キャッシュをクリアして再起動

bashCopy coderm -rf .vite node_modules/.cache
yarn dev

これで CSS HMR が正常に動作するようになりました。Tailwind CSS のクラス変更が即座に反映されるようになります。

実例 2：CSS Modules のインポートミス

React コンポーネントで CSS Modules を使用している際に、スタイルが適用されなかった事例です。

問題の発生

以下のようなコンポーネントで、ボタンにスタイルが適用されません。

typescriptCopy code// Button.tsx
import './Button.module.css';

export const Button = () => {
  return <button className='button'>クリック</button>;
};

ブラウザで確認すると、クラス名がハッシュ化されておらず、通常の button というクラス名がそのまま使われていました。

原因の特定

CSS Modules ファイルを通常の CSS ファイルとしてインポートしているため、CSS Modules の機能（スコープ化）が働いていませんでした。

解決手順

手順 1：インポート方法を修正

typescriptCopy code// Button.tsx
// ❌ 誤った方法を修正
// import './Button.module.css'

// ✅ 正しい方法
import styles from './Button.module.css';

CSS Modules は default エクスポートとしてインポートする必要があります。

手順 2：クラス名の適用方法を修正

typescriptCopy codeexport const Button = () => {
  return (
    <button className={styles.button}>クリック</button>
  );
};

インポートした styles オブジェクトから、プロパティとしてクラス名を参照します。

手順 3：CSS ファイルの内容確認

cssCopy code/* Button.module.css */
.button {
  padding: 10px 20px;
  background-color: #3b82f6;
  color: white;
  border: none;
  border-radius: 4px;
  cursor: pointer;
}

.button:hover {
  background-color: #2563eb;
}

CSS ファイル自体は変更不要です。インポートと使用方法を修正するだけで、正しく動作するようになります。

手順 4：TypeScript の型安全性を追加

typescriptCopy code// vite-env.d.ts
/// <reference types="vite/client" />

declare module '*.module.css' {
  const classes: { readonly [key: string]: string };
  export default classes;
}

declare module '*.module.scss' {
  const classes: { readonly [key: string]: string };
  export default classes;
}

この型定義により、TypeScript が CSS Modules のプロパティをチェックしてくれるようになります。

手順 5：動作確認

ブラウザで確認すると、クラス名が Button__button___2Xk9a のようにハッシュ化され、スタイルが正しく適用されるようになりました。

さらに、CSS を変更すると HMR によって即座にブラウザに反映され、快適な開発体験が実現できます。

実例 3：キャッシュによる古いスタイルの残存

依存パッケージを更新した後、古い CSS が表示され続ける事例です。

問題の発生

PostCSS のプラグインを更新し、設定も変更したのに、ブラウザには古いスタイルが表示され続けていました。

エラーは表示されず、開発サーバーも正常に動作しているように見えます。しかし、新しい CSS ルールが一切反映されません。

原因の特定

.vite ディレクトリと node_modules​/​.cache に古いビルド結果が残っており、Vite がそのキャッシュを使い続けていました。

以下のコマンドでキャッシュの状態を確認できます。

bashCopy codels -la .vite/

結果：

textCopy codedrwxr-xr-x   deps
-rw-r--r--   _metadata.json

キャッシュファイルの更新日時が、最後のパッケージ更新よりも古い日付になっていました。

解決手順

手順 1：開発サーバーを停止

bashCopy code# Ctrl+C でサーバーを停止

サーバーが実行中の状態でキャッシュを削除すると、予期しない動作が発生する可能性があります。

手順 2：Vite のキャッシュを削除

bashCopy coderm -rf .vite

この操作で、Vite の事前バンドルキャッシュがすべて削除されます。

手順 3：node_modules のキャッシュを削除

bashCopy coderm -rf node_modules/.cache

PostCSS や CSS 関連パッケージのキャッシュも削除します。

手順 4：ブラウザのキャッシュも念のため削除

Chrome の場合：

1. DevTools を開く（F12）
2. Application タブを選択
3. 「Clear storage」をクリック
4. 「Clear site data」を実行

手順 5：開発サーバーを再起動

bashCopy codeyarn dev

サーバーが起動すると、Vite は依存関係を再スキャンし、新しいキャッシュを生成します。初回起動は通常より時間がかかりますが、これは正常な動作です。

手順 6：動作確認

ブラウザでページをリロード（Cmd+Shift+R）し、最新の CSS が適用されていることを確認します。DevTools の Network タブで、CSS ファイルが正しく読み込まれているか確認するとより確実です。

これにより、キャッシュ問題が完全に解決され、HMR も正常に動作するようになりました。

実例 4：複合的な問題の切り分け

PostCSS、CSS Modules、キャッシュの複数の問題が同時に発生していた事例です。

問題の発生

新しく参加したプロジェクトで、CSS を変更しても何も反映されない状況でした。エラーメッセージも特に表示されず、原因の特定が困難な状態です。

段階的な診断と解決

診断手順 1：基本的な動作確認

まず、HMR が完全に動作していないのか、CSS だけの問題なのかを確認します。

typescriptCopy code// App.tsx
console.log('App component loaded');

JavaScript の変更は HMR で反映されることを確認できました。つまり、CSS 特有の問題であると判断できます。

診断手順 2：PostCSS の設定確認

bashCopy codels postcss.config.js

結果：No such file or directory

PostCSS の設定ファイルが存在していませんでした。これが第一の問題です。

解決アクション 1：PostCSS 設定を作成

javascriptCopy code// postcss.config.js
export default {
  plugins: {
    autoprefixer: {},
  },
};

最小限の設定で作成し、サーバーを再起動します。

診断手順 3：CSS Modules の使用状況確認

typescriptCopy code// 既存コード
import styles from './App.module.css';

function App() {
  return <div className={styles.container}>App</div>;
}

インポート方法は正しく見えますが、型定義を確認します。

bashCopy codecat vite-env.d.ts

結果：CSS Modules の型定義が存在していません。これが第二の問題です。

解決アクション 2：型定義を追加

typescriptCopy code// vite-env.d.ts
/// <reference types="vite/client" />

declare module '*.module.css' {
  const classes: { readonly [key: string]: string };
  export default classes;
}

診断手順 4：キャッシュの確認

bashCopy codels -la .vite/

結果：1 週間前の日付のキャッシュが残っています。これが第三の問題です。

解決アクション 3：完全なキャッシュクリア

bashCopy coderm -rf .vite node_modules/.cache
yarn cache clean
yarn install
yarn dev

これで、すべての問題が解決され、CSS HMR が正常に動作するようになりました。

診断結果のまとめ

#	問題	症状	解決方法
1	PostCSS 設定なし	CSS 処理が不完全	postcss.config.js を作成
2	型定義の不足	TypeScript エラー	vite-env.d.ts に型定義追加
3	古いキャッシュ	変更が反映されない	キャッシュを完全削除

複数の問題が同時に発生している場合は、このように段階的に切り分けることが重要です。一つずつ確実に解決していくことで、最終的に正常な状態に戻すことができます。

以下の図は、複合的な問題の診断フローを示しています。

mermaidCopy codeflowchart TD
  Start["CSS HMR<br/>動作しない"] --> JSCheck{"JavaScript の<br/>HMR は動作？"}

  JSCheck -->|No| ViteIssue["Vite 全体の<br/>問題"]
  JSCheck -->|Yes| CSSIssue["CSS 特有の<br/>問題"]

  CSSIssue --> ConfigCheck["PostCSS 設定<br/>を確認"]
  ConfigCheck --> ConfigExists{"設定ファイル<br/>存在？"}

  ConfigExists -->|No| CreateConfig["設定ファイル<br/>作成"]
  ConfigExists -->|Yes| NextCheck1["次の診断へ"]
  CreateConfig --> TestFix1{"解決？"}

  TestFix1 -->|Yes| Resolved["完了"]
  TestFix1 -->|No| NextCheck1

  NextCheck1 --> ModuleCheck["CSS Modules<br/>確認"]
  ModuleCheck --> TypeDef{"型定義<br/>存在？"}

  TypeDef -->|No| AddType["型定義追加"]
  TypeDef -->|Yes| NextCheck2["次の診断へ"]
  AddType --> TestFix2{"解決？"}

  TestFix2 -->|Yes| Resolved
  TestFix2 -->|No| NextCheck2

  NextCheck2 --> CacheCheck["キャッシュ確認"]
  CacheCheck --> CacheClean["キャッシュ<br/>クリア"]
  CacheClean --> Resolved

  ViteIssue --> ViteConfig["Vite 設定<br/>確認"]
  ViteConfig --> Resolved

まとめ

CSS HMR が反映されない問題は、PostCSS、CSS Modules、キャッシュという 3 つの主要な要素から切り分けることで、効率的に解決できます。

本記事で紹介したチェックリストを順番に実行することで、ほとんどの CSS HMR の問題は解決できるでしょう。特に重要なポイントを以下にまとめます。

PostCSS 関連の要点

• postcss.config.js の存在と正しい設定を確認する
• プラグインのバージョン互換性を必ずチェックする
• エラーログを注意深く読み、具体的なエラーコードから原因を特定する

CSS Modules 関連の要点

• インポートは import styles from '.​/​file.module.css' の形式で行う
• TypeScript を使用する場合は型定義ファイルを必ず追加する
• グローバルスタイルと CSS Modules を混在させる場合は :global を使う

キャッシュ関連の要点

• 問題が解決しない場合は、段階的にキャッシュをクリアする
• ブラウザキャッシュ、.vite、node_modules​/​.cache の順で削除する
• 最終手段として完全なクリーンインストールを実施する

トラブルシューティングでは、焦らず一つずつ確認していくことが大切です。エラーメッセージが表示されない場合でも、本記事のチェックリストに従って診断を進めることで、確実に原因を特定できます。

快適な開発体験を実現するために、CSS HMR を正常に動作させることは非常に重要です。この記事が、皆さんの開発効率向上に少しでも貢献できれば幸いです。

関連リンク

• Vite 公式ドキュメント - CSS の扱い
• Vite 公式ドキュメント - CSS Modules
• PostCSS 公式サイト
• PostCSS 8 移行ガイド
• Tailwind CSS 公式ドキュメント
• Autoprefixer 公式リポジトリ
• Vite HMR API