「また動いてない！💢」CSS ビルド・デプロイ時のスタイル適用問題を血と汗で解決した記録 😤 - Vite + Remix + Cloudflare

こんな絶望を味わったことありませんか？😭

• 「ローカルでは完璧なのに、デプロイすると崩れる…」 - なんでだよ！！！
• 「ビルドは成功してるのに、スタイルが効かない…」 - 意味がわからない…
• 「ユーザーから『デザインがおかしい』って言われる…」 - 地獄のような恥ずかしさ
• 「何時間もかけて作ったCSSが水の泡…」 - やる気が完全に消失

そうなんです。僕も全く同じ地獄を体験しました。特に**「またスタイルがあたってない」** というユーザーからの報告を受けたときは、本当に穴があったら入りたかった…😢

あの時の絶望感は今でも覚えています。夜中の3時まで原因を探して、コーヒーを7杯飲んで、最終的に壁を殴りたくなったことも…（実際には殴ってませんが）

でも諦めませんでした。この問題を解決して、同じ苦しみを味わう人を一人でも減らしたい。そんな想いで血と汗と涙（主に汗）で解決策を見つけました！

発生環境

• フレームワーク: Remix with Vite
• スタイリング: Tailwind CSS
• ホスティング: Cloudflare Pages
• ビルドツール: Vite

問題の症状

1. ビルドは正常完了: npm run build は成功
2. CSS ファイル生成済み: build/client/assets/ に CSS ファイルが存在
3. スタイル未適用: 実際のサイトでスタイルが反映されない
4. ファイル参照問題: 複数の CSS ハッシュファイルが生成されている

調査プロセス

1. ビルド成果物の確認

# CSS ファイルの存在確認
ls -la build/client/assets/ | grep "\.css"
# 結果: 複数のCSSファイルが存在
# -rw-r--r-- 1 user user  45432  8月 30 18:19 root-B1wHN1Kf.css
# -rw-r--r-- 1 user user  40637  8月 30 14:52 root-CKJsf7Yk.css
# -rw-r--r-- 1 user user  43068  8月 30 14:52 root-CoCJsXi6.css

2. マニフェストファイルの確認

grep -r "root-.*\.css" build/client/

問題発見: 複数のマニフェストファイルが異なるCSSファイルを参照していることが判明。

3. 実際の HTML 参照確認

curl -s "https://deployed-url.pages.dev" | grep -o 'href="[^"]*\.css[^"]*"'
# 結果: href="/assets/root-B1wHN1Kf.css"

4. CSS ファイルアクセス確認

curl -s -I "https://deployed-url.pages.dev/assets/root-B1wHN1Kf.css"
# 結果: HTTP/2 200 - ファイル自体はアクセス可能

根本原因

複数の不整合なビルド成果物の蓄積

1. インクリメンタルビルドの副作用: 過去のビルドで生成された古いCSSファイルが残存
2. マニフェスト不整合: 複数のマニフェストファイルが異なるCSSハッシュを参照
3. キャッシュ問題: ブラウザとCDNレベルでのキャッシュ不整合

解決策

クリーンビルドの実行

# 既存ビルド成果物を完全削除
rm -rf build

# 完全な再ビルド実行
npm run build

ビルド結果の確認

# 単一のCSSファイルのみ生成されることを確認
ls -la build/client/assets/ | grep "\.css"
# 期待結果: 1つのCSSファイルのみ

# マニフェストの一意性確認
grep -r "root-.*\.css" build/client/ | head -1

デプロイとテスト

# クリーンビルド後のデプロイ
npx wrangler pages deploy

# 新デプロイのテスト
curl -s "https://new-deployment-url.pages.dev" | grep -A 10 -B 2 "記事を検索"

結果

• スタイル完全復旧: 全てのTailwind CSSクラスが正常適用
• 検索バーの表示: backdrop-blur-sm、bg-white/10 などの効果が正常に動作
• レスポンシブデザイン: モバイル・デスクトップでの表示が正常

技術的考察

Vite ビルドシステムの特性

// vite.config.ts での設定例
export default defineConfig({
  build: {
    rollupOptions: {
      output: {
        assetFileNames: 'assets/[name]-[hash][extname]'
      }
    }
  }
})

インクリメンタルビルドのリスク

1. ハッシュ不整合: 同名ファイルでも異なるハッシュが生成される可能性
2. マニフェスト混在: 複数ビルドのマニフェストが混在
3. 参照エラー: 存在しないファイルへの参照が発生

予防策

1. 本番デプロイ時のクリーンビルド

{
  "scripts": {
    "build": "node scripts/build-articles.mjs && npx remix vite:build",
    "build:clean": "rm -rf build && npm run build",
    "deploy": "npm run build:clean && npx wrangler pages deploy"
  }
}

2. CI/CD での自動化

# GitHub Actions例
- name: Clean Build
  run: |
    rm -rf build
    npm run build
    
- name: Verify Build
  run: |
    test -f build/client/assets/*.css
    ls -la build/client/assets/

3. ビルド検証スクリプト

#!/bin/bash
# build-verify.sh
CSS_FILES=$(ls build/client/assets/*.css | wc -l)
if [ $CSS_FILES -ne 1 ]; then
    echo "Error: Expected 1 CSS file, found $CSS_FILES"
    exit 1
fi
echo "Build verification passed"

あなたは、もう同じ苦しみを味わう必要はありません 😌

この記事を読み終えたあなたは、僕が夜中の3時に味わった絶望を経験することはありません。あの時の僕に、この解決策を教えてあげたかった…😢

💝 あなたが手に入れるもの:

• 「なんで動かないの？」から解放される - 根本原因がわかるから、もう迷わない
• デプロイへの安心感 - 「今度こそ大丈夫」という確信
• ユーザーからの信頼 - 「いつも完璧ですね」と言われる日
• 深夜デバッグからの卒業 - 早く家に帰れるように

💪 僕が学んだ大切なこと:

技術的な問題って、実は**「なぜ？」を5回繰り返す**ことで必ず解決できるんです。表面的な症状に騙されちゃダメ。僕も最初はCSSファイルがあるかないかばかり確認してて、本当の原因に気づくまで時間がかかりました。

でも、根本原因を理解すれば、同じ問題は二度と起こらない。そして、この経験は必ずあなたの技術力を一段階上げてくれます。

🎉 最後のメッセージ:

もう深夜にコーヒー7杯飲みながらデバッグする必要はありません。この記事の解決策を使って、安心してデプロイできる日々を手に入れてください。

そして、もし同じ問題で困っている仲間がいたら、ぜひこの記事を教えてあげてくださいね 😊

今日から実践できること:

1. デプロイ前に必ずクリーンビルドを実行する
2. ビルド検証スクリプトをCI/CDに組み込む
3. 「なぜ？」を5回繰り返す習慣をつける

あなたのストレスフリーな開発ライフの始まりです ✨