iOS の PWA でハマるポイントまとめ

はじめに

PWA（Progressive Web App）は、Web 技術でネイティブアプリに近い体験を提供できる。しかし iOS では Android と比べて制約が多く、独特のハマりポイントがある。

CancelNavi を Claude Code で開発する中で実際に遭遇した問題と、その解決策をまとめる。

問題の発見

2026年1月19日、開発日記にはこう書いた。

iOSでPWAとしてホーム画面に追加したとき、古いアイコンがキャッシュされていた 新しいロゴに更新したのに、古いアイコンが表示され続ける問題 ユーザーから「アイコンが違う」という報告を受けた

ロゴを更新したのに、ユーザーの端末では古いアイコンが表示される。これが iOS の PWA 特有の問題だった。

iOS PWA の主なハマりポイント

1. favicon / apple-touch-icon のキャッシュ問題

開発日記に詳しく記録していた。

iOSのキャッシュの挙動が分かりにくい ホーム画面のアイコンは一度追加すると更新されにくい Web App Manifestのアイコン設定だけでは不十分なケースがあった

iOS ではホーム画面に追加したアイコンが強力にキャッシュされる。Manifest を更新しても、既存ユーザーのアイコンは変わらない。

解決策: apple-touch-icon を明示的に指定する。

// app/layout.tsx
export const metadata = {
  icons: {
    icon: '/favicon.ico',
    apple: '/apple-touch-icon.png',
  },
};

開発日記にも書いた。

apple-touch-iconは明示的にlinkタグで指定した方が確実

2. apple-touch-icon の配置場所

Next.js App Router では、public/apple-touch-icon.png に置くだけでは認識されないことがある。

開発日記より。

Next.js App Routerでは、layout.tsxのheadに直接追加するのが確実 /apple-icon.pngをpublicに置くだけでは認識されないことがあった

解決策: metadata で明示的に指定する。

// app/layout.tsx
export const metadata = {
  icons: {
    apple: [
      { url: '/apple-touch-icon.png', sizes: '180x180', type: 'image/png' },
    ],
  },
};

3. ホーム画面追加後のアイコン更新

既にホーム画面に追加済みのユーザーに対しては、アイコン更新が反映されにくい。

開発日記に書いた現実的な対処法。

ユーザーに「一度削除して再追加してください」と案内するのも一つの手

技術的な解決が難しい場合は、ユーザーへの案内で対応する。

4. スタンドアロンモードの挙動

iOS の PWA はスタンドアロンモード（ホーム画面から起動）とブラウザモードで挙動が異なる。

// スタンドアロンモードの検出
const isStandalone = window.matchMedia('(display-mode: standalone)').matches
  || window.navigator.standalone;  // iOS Safari 用

スタンドアロンモードでは「戻る」ボタンがないため、アプリ内でナビゲーションを完結させる必要がある。

5. Service Worker の制限

iOS Safari では Service Worker の機能に制限がある。

• バックグラウンド同期: 非対応
• プッシュ通知: iOS 16.4 以降で対応（ただし制限あり）
• キャッシュ容量: 50MB 程度

Android では動作するオフライン機能が、iOS では動かないことがある。

iOS PWA 開発のベストプラクティス

CancelNavi の PWA 対応で Claude Code と一つずつ問題を潰しながらまとめたベストプラクティスを紹介する。

1. apple-touch-icon を確実に設定

<!-- public/apple-touch-icon.png を用意 -->
<!-- サイズは 180x180px が推奨 -->

// app/layout.tsx の metadata で明示
export const metadata = {
  icons: {
    apple: '/apple-touch-icon.png',
  },
};

2. Web App Manifest の設定

{
  "name": "App Name",
  "short_name": "App",
  "start_url": "/",
  "display": "standalone",
  "background_color": "#ffffff",
  "theme_color": "#000000",
  "icons": [
    {
      "src": "/icon-192.png",
      "sizes": "192x192",
      "type": "image/png"
    },
    {
      "src": "/icon-512.png",
      "sizes": "512x512",
      "type": "image/png"
    }
  ]
}

3. iOS 実機での定期的なテスト

開発日記の「次やること」にも書いた。

iOSでの動作確認を定期的に行う

シミュレータではなく実機でテストすることが重要。特にホーム画面追加後の挙動は実機でしか確認できない。

学んだこと

開発日記には2つの教訓を書いた。

• iOSのPWAはキャッシュ周りがAndroidより厄介
• apple-touch-iconは明示的にlinkタグで指定した方が確実

iOS の PWA は Android に比べて制約が多い。「Android で動くから iOS でも動く」とは限らない。

まとめ

iOS で PWA を開発する際の注意点。

1. apple-touch-icon を明示的に設定: Manifest だけでは不十分
2. キャッシュの挙動を理解: 更新が反映されにくい
3. スタンドアロンモードを考慮: ナビゲーションの設計
4. 実機テストを定期的に: シミュレータでは分からない問題がある

iOS ユーザーを無視できない日本市場では、これらの対策は必須だ。

---

関連記事

• LINE 内ブラウザで OAuth 認証が動かない問題への対処