Next.js 15 + GitHub PagesでCSSが反映されない問題を解決した話（App Router対応・Tailwind・TypeScript）

はじめに

この記事では、Next.js 15（App Router使用）で作成したプロジェクトをGitHub Pagesにデプロイする過程で遭遇した、「CSSが効かない問題」とその解決方法について詳しくまとめます。

特に、静的サイトエクスポート (output: "export") を使うときに .nojekyll ファイルが必要 なことに気づかずハマった経験をシェアします。

---

前提

• Next.js 15
• App Router（pagesディレクトリではなくappディレクトリ使用）
• Tailwind CSS + TypeScript構成
• GitHub Pagesでホスト
• Docker + DevContainer環境で開発

プロジェクト作成と設定

1. Next.js プロジェクト作成

npx create-next-app@latest my-app --typescript --tailwind --eslint --src-dir --app

2. next.config.ts を編集

/** @type {import('next').NextConfig} */
const nextConfig = {
  output: "export",
  images: { unoptimized: true },
  distDir: "../docs", // ビルド出力をdocsにする（GitHub Pages対応）
};

export default nextConfig;

3. Makefile にビルドコマンドを用意

build:
	docker compose ${DOCKER_COMPOSE_FILE_PATH} ${PROJECT_FLAG} exec ${USER_FLAG} workspace bash -c 'cd ${WORKDIR}/src && npm run build'
	echo > ../docs/.nojekyll

ここで 超重要ポイント ✨

🔥 .nojekyll を必ず作成する！

GitHub Pages はデフォルトで Jekyll という静的サイトジェネレーターが動きます。

• _next/ というディレクトリがあると、Jekyllが勝手に除外しようとします。
• これにより CSSやJSが読み込めないバグ が発生します！！

→ ビルド後に必ず .nojekyll ファイルを設置することで解決します。

実際のディレクトリ構成

my-app/
  docs/ ← ここにビルド成果物が出力される
    _next/
    index.html
    favicon.ico
    など
  src/
  docker-compose.yml
  .devcontainer/
  Makefile
  .env
  ...

GitHub側の設定

1. GitHubリポジトリ作成

リポジトリ名は hellomyzn.github.io のようにしておくとパス設定が楽です。

2. Pages設定

GitHub Pagesの設定で、

• Branch: master（またはmain）
• Folder: /docs
  を選択してください。

注意ポイントまとめ

項目	説明
distDir	../docs にする（docsフォルダへビルド成果物を出す）
.nojekyll	必ず作成！_next/を守るため

おわりに

最初、なぜCSSが効かないのか全く分からずすごくハマりました。

最終的に、

• .nojekyll
  の設定ミスが原因だったことがわかり、無事表示されました！

同じように悩んでいる人の助けになれば嬉しいです！

---

この記事が参考になったら「いいね」やコメントもらえると励みになります☺️