GitHub Pages がデプロイできない／サイトが反映されない

要約

GitHub Pages がデプロイされない・反映されないとき、原因の大半は Settings → Pages の Source 設定、ワークフローの権限不足、Jekyll による隠しファイル除外、独自ドメインの DNS 設定不備 の 4 つに集約される。
Actions のログと Pages 画面を交互に確認すれば、ほぼ確実に切り分けできる。

よくある原因

1. Source が実際のデプロイ元と一致していない（例: main の root を指定しているが、実成果物は gh-pages ブランチに push されている）
2. ワークフローの permissions に pages: write と id-token: write が無く、actions/deploy-pages が 403 で落ちる
3. _next/ や _app/ などアンダースコア始まりのディレクトリが Jekyll に無視され、HTML は表示されるが JS / CSS が 404 になる
4. 独自ドメインの DNS が GitHub の Anycast IP に向いていない、CNAME ファイルがリポジトリに無い、HTTPS プロビジョニング前にドメインを切り替えている

解決策

1. Source とワークフローを揃える

Actions ベースでデプロイするなら、Settings → Pages → Build and deployment → Source を GitHub Actions に変更し、ワークフローを 3 ステップで構成する。

name: Deploy to Pages
on:
  push:
    branches: [main]
permissions:
  contents: read
  pages: write
  id-token: write
concurrency:
  group: pages
  cancel-in-progress: false
jobs:
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/configure-pages@v5
      - uses: actions/upload-pages-artifact@v3
        with:
          path: ./out
      - id: deployment
        uses: actions/deploy-pages@v4

ブランチデプロイなら、Source に出力ブランチ（多くは gh-pages）と root / docs フォルダを正しく指定する。

2. .nojekyll を置いて静的アセットを救済する

touch out/.nojekyll

Next.js (out/) や Vite (dist/) などのフレームワーク出力には、ビルド後にこの 1 ファイルを必ず追加する。public/.nojekyll を置いておけば、ビルド時に成果物へコピーされるフレームワークも多い。

3. 独自ドメインの DNS を揃える

apex は GitHub の Anycast IP を A レコードに、サブドメインは <user>.github.io への CNAME を設定する。
値は Configuring a custom domain の表が常に最新。
HTTPS の自動プロビジョニングが終わるまで Enforce HTTPS のチェックは入れない。

4. Pages 画面と Actions ログを突き合わせる

Actions の deploy-pages ステップに表示される URL と、Pages 画面の Visit site の URL が一致しているか確認する。
一致しているのにブラウザで 404 なら、ビルド成果物の中身（index.html の有無や _next/ 配下）を Artifact からダウンロードして確認する。