投稿する
マガジン
著者：アソバース編集部公開：更新：約10分で読めます

GitHub Pagesで公開するとCSSが効かない・404になる：パスと公開設定の見直し方

AIを使いこなす

Claudeで執筆し、GPTで自動校閲・修正しています。

フォルダと紙片の位置関係を手で確かめる様子
記事の内容をもとに制作したAI生成イメージです。実際の製品画面や検証結果の写真ではありません。

結論から言うと、原因は多くの場合「公開元の設定」「CSSなどを指すパス」「ファイル名の大文字小文字」のどれかです。この順で一つずつ確かめれば、闇雲にコードを書き換えずに切り分けられます。 ただし最初に、症状が2種類あることを分けてください。 • ページ自体が404になる → 公開元とエントリファイル（index.html）を疑う • ページは出るがCSSや画像だけ効かない → パスと大文字小文字を疑う 以下の確認リストは、この分岐を入口にしています。なお、文中の example-user、my-tool などは説明用の例で、私が実際に操作した結果ではありません。

この記事の目次
  1. まず症状を分ける：ブラウザで何が404なのかを見る
  2. 確認1：公開元（ブランチとフォルダ）が合っているか
  3. 確認2：CSS・画像へのパスが公開URLに合っているか
  4. 確認3：ファイル名の大文字小文字が一致しているか
  5. 確認4：反映待ちとキャッシュを疑うのは最後
  6. そのまま使える確認リストとAIへの依頼文
  7. それでも直らないとき

まず症状を分ける：ブラウザで何が404なのかを見る

公開URLを開き、ブラウザの開発者ツール（多くのブラウザでF12キー）の「Network（ネットワーク）」タブを開いて再読み込みします。赤く表示される、または状態が404のファイル名を控えてください。ここで見るのは次の2点です。

  1. 404になっているのはページ本体か、style.css などの付属ファイルか
  2. 404になっているURLの文字列（どこを探しに行っているか）

GitHub Pagesのプロジェクトサイトは、公式ドキュメントによると https://<owner>.github.io/<repository>/ の形のURLで公開されます（What is GitHub Pages?）。つまり、リポジトリ名がURLの途中に入ります。ローカルで http://localhost/style.css のように動いていても、公開後は https://example-user.github.io/my-tool/style.css が正しい場所になります。この差が、次に見るパス問題の正体です。

確認1：公開元（ブランチとフォルダ）が合っているか

ページ自体が404なら、最初にここです。リポジトリの Settings → Pages → 「Build and deployment」を開きます。GitHub公式の説明では、公開元は「ブランチから公開」か「GitHub Actionsワークフロー」の2通りで、ブランチ公開の場合はブランチと、フォルダ（ルート / または /docs）を選びます（Configuring a publishing source）。

見るべきポイントは次のとおりです。

  • 選んだブランチに、最新のファイルが実際にプッシュされているか（別ブランチで作業していないか）
  • フォルダ設定が /docs なのに、ファイルがリポジトリ直下にある（またはその逆）になっていないか
  • 公開元に選んだフォルダを削除していないか（公式ではビルドエラーになるとされています）

さらに、エントリファイルは index.html、index.md、README.md のいずれかを、公開元フォルダの最上位に置く必要があります（Creating a GitHub Pages site）。/docs を公開元にしているなら、docs/index.html が必要です。

確認2：CSS・画像へのパスが公開URLに合っているか

ページは出るのにデザインが崩れるなら、ここが最有力です。パスには大きく2種類あります。MDNの説明では、/ で始まるパスはサイトのルートからの位置、/ で始まらないパスは今のファイルからの相対位置を指します（MDN: Creating links）。

プロジェクトサイトでは、「サイトのルート」が example-user.github.io 直下であり、/my-tool/ ではありません。そのため次のような差が出ます（説明用の例）。

html
<!-- 崩れやすい：example-user.github.io/style.css を探しに行く -->
<link rel="stylesheet" href="/style.css">

<!-- 動きやすい：このHTMLと同じ場所の style.css -->
<link rel="stylesheet" href="style.css">

<!-- HTMLがサブフォルダにある場合：一つ上の css フォルダ -->
<link rel="stylesheet" href="../css/style.css">

直し方の基本は、/ から始まるパスを、style.css や ./css/style.css のような相対パスにすることです。../ の数は、HTMLファイルの置き場所から数えます。

ReactやViteなどのビルドツールを使っている場合は、ビルド後の出力フォルダを公開すること、そして公開先のパス設定をツール側で指定することが別途必要になることがあります。この記事ではツールごとの設定までは扱いません。

確認3：ファイル名の大文字小文字が一致しているか

「自分のPCでは動くのに」という症状の典型がこれです。GitHub公式の404対処ページには、index.html のファイル名は大文字小文字を区別し、Index.html では動かないと明記されています（Troubleshooting 404 errors）。

それ以外の画像やCSSについては、そのページに同様の明記は確認できませんでした。ただ、公開側で名前が違えば別のファイルとして扱われる可能性があるため、HTMLに書いた名前とリポジトリ上の名前を一字一句同じにそろえるのが安全です。ローカルのOSによっては大文字小文字の違いを許容するので、手元で気づきにくくなります。

照合の方法は簡単です。GitHubのリポジトリ画面でファイル名をそのまま見て、HTMLの href・src と見比べます。

  • images/Logo.png、リポジトリ上の名前：images/logo.png、判定：不一致（直す）
  • Style.css、リポジトリ上の名前：style.css、判定：不一致（直す）
  • index.html、リポジトリ上の名前：Index.html、判定：公式に動かないと明記
  • 日本語や空白入りの名前、リポジトリ上の名前：—、判定：半角英数字と - に改名すると確認が楽

確認4：反映待ちとキャッシュを疑うのは最後

上の3つを直しても変わらないとき、初めて「反映の遅れ」を疑います。公式ドキュメントでは、プッシュ後にサイトへ反映されるまで最大10分かかることがあり、変わらない場合は1時間待ってからビルドエラーを確認するよう案内されています（Creating a GitHub Pages site）。

待つ間にできることは次のとおりです。

  • リポジトリの Actions タブで、ビルドや公開が失敗（赤）になっていないか見る
  • Settings → Pages の「Visit site」から公開URLを開き直す
  • スーパーリロードやシークレットウィンドウで、古い表示が残っていないか確かめる

なお、GitHub Actionsのワークフロー内で GITHUB_TOKEN を使って行ったコミットは、ブランチ公開の自動ビルドを起動しないと公式に書かれています。自動化を組んでいて更新されない場合の手がかりになります。

そのまま使える確認リストとAIへの依頼文

確認リスト（上から順に）

  1. [ ] Networkタブで、404なのは本体か付属ファイルかを控えた
  2. [ ] Settings → Pages で公開元のブランチとフォルダが、ファイルのある場所と一致している
  3. [ ] 公開元フォルダの最上位に index.html（小文字）がある
  4. [ ] href・src に、/ で始まるパスが残っていない（または意図して使っている）
  5. [ ] ../ の数がHTMLの置き場所と合っている
  6. [ ] HTML内のファイル名とリポジトリ上のファイル名が、大文字小文字まで一致している
  7. [ ] Actionsタブにエラーがなく、プッシュから十分な時間が経った

AIに渡す依頼文（コピーして使えます）

AIは、渡された情報の範囲でしか判断できません。次の形で、必要な情報を貼ってください。APIキーや個人情報は貼らず、必要なら xxxx に置き換えます。

GitHub Pagesで公開したサイトのCSSが効かず（または404になり）困っています。
原因の候補を、可能性が高い順に最大3つ挙げ、それぞれ確認方法を教えてください。
断定せず、私が確認すべき点を示してください。

【公開URL】https://example-user.github.io/my-tool/
【404になっているURL（Networkタブ）】https://example-user.github.io/style.css
【Settings > Pagesの公開元】ブランチ main、フォルダ /(root)
【フォルダ構成】
  index.html
  css/style.css
  images/Logo.png
【index.htmlのhead部分】
  <link rel="stylesheet" href="/css/style.css">

上の入力例（説明用）なら、AIの回答は「/css/style.css が example-user.github.io 直下を探している」という指摘になるはずです。ただし、AIの回答は仮説です。実際に直したあと、公開URLをもう一度開いて、人が自分の目で表示を確認してください。リポジトリを非公開から公開に変えたときなどは、再構築を待つ必要もあります。

それでも直らないとき

公式の404対処ページは、DNS設定（独自ドメイン利用時）やGitHubのステータスページの確認も挙げています。独自ドメインを使っていない通常のプロジェクトサイトなら、まず本記事の確認1〜3で原因が見つかるケースが多いはずです。独自ドメインを使っている場合は、パスの前にドメイン側の設定も確認対象になります。

出典・参考資料

マガジン一覧に戻る