Cloudflare Pages デプロイエラー解決：_routes.json の100文字制限対応

問題の概要

Cloudflare Pagesへのデプロイ時に以下のエラーが発生しました：

X [ERROR] Invalid _routes.json file found at: C:\Users\numbe\Git_repo\mdx-playground\apps\web\dist\_routes.json

  Detected rules the are over the 100 character limit. Please make sure that each include and
  exclude routing rule is at most 100 characters long.

エラーの原因

Nuxt + Nitro（cloudflare-pages preset）でビルドすると、静的アセット（画像、Excel、その他のファイル）がdist/_routes.jsonのexcludeセクションに個別のファイルパスとして追加されます。

問題のあったファイル名の例：

/2025-11-23/www.zeiri4.com_shoukai_split-step-form_chat-ui__businessType=3&businessGroup=3&businessStep=1&promotionPageId=297&trackingCode=chat_ui_firstQuestion_removeCompanyName&skipCompanyName=true.png （197文字）

Cloudflare Pagesは各ルーティングルールに100文字までの制限を設けているため、このような長いパスを含むルールはエラーになります。

解決方法

1. 一時対処：ファイル名のリネーム

長いファイル名を短くリネームすることで一時的に解決できますが、これは根本的な解決にはなりません。

# 例
mv "長いファイル名.png" "short-name.png"

2. 恒久対処：ビルド後スクリプトでワイルドカードパターンを使用

これが推奨される解決方法です。

Nitroが生成する _routes.json を、ビルド後に自動的にワイルドカードパターンを使用したバージョンに置き換えます。

実装手順

ビルド後スクリプトの作成

apps/web/scripts/fix-routes.mjs を作成：

import { writeFile } from 'node:fs/promises';
import { existsSync } from 'node:fs';
import { resolve, dirname } from 'node:path';
import { fileURLToPath } from 'node:url';

const __dirname = dirname(fileURLToPath(import.meta.url));
const routesPath = resolve(__dirname, '../dist/_routes.json');

if (existsSync(routesPath)) {
  const routes = {
    version: 1,
    include: ["/*"],
    exclude: [
      "/_nuxt/*",
      "/dump.pages.sql",
      "/favicon.ico",
      "/robots.txt",
      "/data/*",
      "/excel/*",
      "/images/*",
      "/__nuxt_content/*",
      "/20*/*"  // 日付ディレクトリの画像ファイル
    ]
  };

  await writeFile(routesPath, JSON.stringify(routes, null, 2));
  console.log('✓ Updated _routes.json with wildcard patterns for Cloudflare Pages');
} else {
  console.warn('⚠ _routes.json not found, skipping...');
}

package.json にpostbuildスクリプトを追加

{
  "scripts": {
    "build": "nuxt build",
    "postbuild": "node scripts/fix-routes.mjs"
  }
}

これにより、pnpm build を実行すると自動的に以下が実行されます：

Nuxtビルド → Nitroが _routes.json を生成
postbuild スクリプトが実行 → ワイルドカードパターンで上書き

修正後の _routes.json

{
  "version": 1,
  "include": ["/*"],
  "exclude": [
    "/_nuxt/*",
    "/dump.pages.sql",
    "/favicon.ico",
    "/robots.txt",
    "/data/*",
    "/excel/*",
    "/images/*",
    "/__nuxt_content/*",
    "/20*/*"
  ]
}

すべてのルールが100文字以内に収まっています。

動作確認

cd apps/web
pnpm build
pnpm exec wrangler pages deploy dist

ビルド出力の最後に以下のメッセージが表示されます：

✓ Updated _routes.json with wildcard patterns for Cloudflare Pages

ファイル命名規則のベストプラクティス

ビルド後スクリプトで自動修正されるため、長いファイル名でも問題ありませんが、以下のベストプラクティスに従うことを推奨します：

避けるべきファイル名

日本語を含むファイル名
```
❌ 【狙い筋Aと狙い筋Bの話】.xlsx
✅ targeting-strategy.xlsx
```
日本語はURLエンコードされると1文字が数倍の長さになります。例：【狙い筋Aと狙い筋Bの話】 → 数十文字以上

長いクエリパラメータを含むスクリーンショット名

❌ www.zeiri4.com_shoukai_split-step-form_chat-ui__businessType=3&businessGroup=3&businessStep=1&promotionPageId=297&trackingCode=chat_ui_firstQuestion_removeCompanyName&skipCompanyName=true.png
✅ zeiri4-chat-ui-form.png

スペースや特殊文字を含むファイル名

❌ Generated Image November 24, 2025 - 7_23AM.jpeg
✅ generated-image-2025-11-24.jpeg

推奨されるファイル名

英数字、ハイフン（-）、アンダースコア（_）のみ使用
小文字を使用（大文字小文字の混在を避ける）
意味のある短い名前を付ける
日付を含める場合は YYYY-MM-DD 形式

例：

✅ nvidia-financial-chart.png
✅ tax-consultation-form-2025-11.pdf
✅ user-flow-diagram.drawio

なぜこれが重要か

URLエンコード: 日本語や特殊文字はパーセントエンコーディングされ、文字数が3倍以上に増加
可読性: 英数字の方がURLやパスで読みやすい
互換性: 異なるOS間でのファイル共有時の問題を回避
デバッグ: エラーログやコンソールで識別しやすい

まとめ

問題: Cloudflare Pagesの_routes.jsonには各ルールに100文字制限がある
原因: Nitroが個別ファイルパスを生成し、長いファイル名（特に日本語やURLエンコードされる文字）が制限を超える
解決: ビルド後スクリプトでワイルドカードパターンに自動置換
効果: 今後どんなに長いファイル名を追加しても問題なし
推奨: ファイル名は英数字とハイフン・アンダースコアのみを使用し、短く意味のある名前を付ける