Next.js で作ったサイトを GitHub Pages で公開する方法を爆速で丁寧に説明する

[N/S高等学校 Advent Calendar 2023] の21日目です。12/21って書くと並びがいいですよね。


> (2023年12月26日)
私のポカで文章構成が古いままだったので変更しました。ごめんなさい。
ただ、方法等に変更はありません。


この記事は

1. create-next-app で Next.js アプリを作成
2. GitHub にプッシュ
3. GitHub Actions でビルド＆ GitHub Pages にデプロイ

までの工程をバカみたいに丁寧に書き起こしたものです。

情報が不足していればご指摘いただけると助かります。


# はじめに

授業の一環でサイトを作成する必要が出ました。

普通に Adobe Express や STUDIO を使っても良かったのですが、ちょっと拘ってみたかったので Next.js にトライしてみます。

サイトを作っていく上で Three.js というライブラリを使用する予定だったので、そのために Node.js を使うのであれば、ついでに Next.js も使っちゃおう、というものです。

## 専門用語わからんちん🤷

| これは           |こういうこと|
|:--------------:|--------|
| VSCode         |ファイルの中身を読み書きするためのもの。とても優秀。|
| Node.js        |ライブラリのバージョン管理をしたりする。サイトのテンプレートも作ってくれる。|
| Next.js        |**サイトを作る方**。お仲間に Nuxt.js がいる。|
| Git            |ファイルを記録、管理してくれる。GitHub や GitLab でファイルを公開できる。|
| GitHub Actions |GitHubの色んな作業を自動化してくれる。|
| GitHub Pages   |**サイトを公開する方**。お仲間に Netlity や Vercel がいる。|

足りないところは本文で補足します。

### 環境
mac OS：Ventuna 13.5.1
Google Chrome：114.0.5735.198（Official Build） （arm64）
VSCode：1.84.2
Node.js：20.9.0
Next.js：14.0.3
Git：2.43.0


## 下準備
方法に関しては既に様々な記事がありますので、そちらを参考にしてください。

### VSCode
他に似たようなエディターを持っている場合は、そちらでも問題はありません。
~~いずれ拡張機能が優秀なVSCodeを使うことになるぜへっへっへ…~~

ダウンロード：[Download Visual Studio Code - Mac, Linux, Windows] [^vscode]

### Node.js
ダウンロード：[Download | Node.js] [^nodejs]
入れ方(Windows)：[Node.jsをインストールする - Qiita] [^nodejs_ht]

### Git
ダウンロード：[Git - Downloads] [^git]
入れ方(Windows)：[WindowsにGitをインストールする手順(2023年11月更新)] [^git_ht_w]
入れ方(Mac)：[最新の Git を Mac にインストールする方法 - Qiita] [^git_ht_m]

:::note info
Windows の方は Git Bash でコマンドを実行することになります。
なので、ここで言う `コンソール` は Git Bash のことだと思ってください。
:::

### GitHub
アカウントを作成する必要がありますので、お持ちでない場合は作成してください。

サイト：[GitHub: Let’s build from here] [^github]
作り方：[GitHubアカウント作成 - Qiita] [^github_ht]

:::note warn
ユーザー名はそのままサイトのアドレスでも使われます。
`https://ユーザー名.github.io/` と言った形です。
:::
:::note warn
~~アカウントがもうあって、サブディレクトリにあーだこーだするのがめんどくさい場合、Organization を作成するのがおすすめです。~~
また、こちらを使う場合、ここでいう `ユーザー` は Organization のことだと思ってください。

作り方：[新しい Organization をゼロから作成 - GitHub Enterprise Server 3.10 Docs] [^organization_ht]

(2025/5/17追記) Organization を使うのは最後の手段に留めておいた方がよさそうです。サブディレクトリを使う方が後々楽になるので…（というか、GitHubアカウントを持っていらっしゃるほどお詳しいのであればサブディレクトリで作る方法もあまり難しくはないと思います）
申し訳ありませんが方法等は検索していただけるとありがたいです。
:::


# やるぞ
以下の図に沿って、上から順番に説明していきます。

![](https://i.gyazo.com/092e8b46c7f00f9f143f522d1bcf5316.png)

## サイトを用意するぞ(プロジェクトの作成)

まずはプロジェクトを作成します。
サイトやそれに付属するファイルを纏めてプロジェクトと呼んだりします。

コンソールを開いて、`cd`で作成する場所に移動した後に `npx`を実行します。

```console:コンソールで実行してみてください
$ cd 作成する場所                         ← cd ~/Desktop/Apps みたいな感じです
$ npx create-next-app@latest --use-npm  ← create-next-app を使って作成します
...
Creating a new Next.js app in 実行する場所/example.  ←この場所にプロジェクトがあります
```

![](https://i.gyazo.com/d68802f75e4105abf222af7e752ac706.png)

各項目の細かい解説はこちらの記事を参考にしてください。
[create-next-appを用いたNextjsアプリ構築方法 - Qiita] [^create_next_ht]

:::note
この選択はサイトを公開するまでの間に影響するものではありませんが、
今後サイト作りを調べる際に必要になる情報なので、どの選択をしたのかは覚えておいた方が楽です。多分。
:::

あとはプロジェクトの名前を冠したディレクトリが作られ、その中にテンプレートが出来ています。

プロジェクト内の各ファイルについての説明はここでは行いません。


## ファイルを書き換えるぞ(next.config.jsの書き換え)

作成したプロジェクトを VSCode で開いて、その中にある `next.config.js` に書き足します✍️

```diff_javascript:next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
    // ↓ next build を実行する際に Static Export を利用します。
+   output: 'export'
}

module.exports = nextConfig
```

これでプロジェクト内の編集は完了です。

:::note warn
後でファイルの上書き(プル)をするので、**`next.config.js` 以外のファイルはまだ触らないでください。**
下手に触ると超ややこしいことになります。
:::

## GitHubを準備するぞ(レポジトリの作成)

GitHub で新しくレポジトリを作成します。
レポジトリはプロジェクトと似たような感じだと捉えておけば大丈夫です。

[GitHub: Let’s build from here] [^github]

こちらのサイトに移動して、右上にある `+ ▼` から `New Repository` で作成するためのページに移動します。

![](https://i.gyazo.com/6a3cd085abee875d0e9c9730c4e46008.png)

レポジトリ名を入力します。サイトに接続する時に使うアドレスでもあります。

:::note warn
**`Repository name` は必ず`ユーザー名.github.io`にして、**
**`Public` を選択してください。**

`Repository name` を任意の名前にすると `next.config.js` の `basePath` などを変更する必要が出てきます。(要検索)
:::

![](https://i.gyazo.com/7d678f2ab7c5925e1fa3c281babef9e3.png)

あとは下にスクロールしてから、`Create Repository` をクリックすれば、作成は完了です。


## プロジェクトをアップロードするぞ(GitHubへプッシュ)
先ほどのプロジェクトをこちらのレポジトリにプッシュします。

まず、先ほど作成したレポジトリを見てみると、真ん中あたりにURLがあるので、コピーします。

![](https://i.gyazo.com/60a071b6c41fd445e1d2ef756d6d675e.png)

プロジェクトを作成した時のコンソールを再度開いて、`cd` でプロジェクトに移動した後、`git` でリモートを追加し、プッシュしてみてください。

```console:こんそぉる
$ cd ./プロジェクトの名前        ← 先程の例で言えば ~/Desktop/Apps/example に移動します
$ git remote add origin 先程コピーしたURL   ← リモートを追加
$ git branch -M main                    ← 念の為 main ブランチに移動
$ git push -u origin main               ← プッシュします
```

ユーザー名とパスワードを順番に入力すればプッシュは完了です。

:::note warn
`Password for 〜` と、パスワードを求められますが、GitHub はパスワード認証を廃止しています。
なので、 Access Token を作る必要があります。

作り方はこちらの記事を参考にしてください。
[GitHubにPushできない！？GitHubアクセストークン作成を画像で分かりやすく解説 - Qiita] [^access_token_ht]
:::

GitHub に戻って更新してみると、表示が変わっています。


## 公開するぞ(GitHubActionsの作成)

GitHubの中央上に `⚙️ Settings` があると思います。
クリックで移動してみると項目がいっぱいあります。

左のリストから `Pages` を開いて、`Build and deployment` のすぐ下の `Deploy from a branch` をクリックした後に `GitHub Action` を選択してください。

すると、下の方に候補がいくつか出てきますので、もしそこに `Next.js` があれば `Configure` を押してください。

![](https://i.gyazo.com/877e3afb526d25d054ecf2386b22a028.png)

:::note info
無ければ、真ん中にある `browse all workflows` から Next.js を検索にかけて、出てきた `Next.js` から `Configure` を押してください。

![](https://i.gyazo.com/c7ab1e5e1ba6c65809eca029a0598968.png)
:::

そうすると、ビルドやデプロイをするまでの工程が書かれたYamlファイルが表示されますので、一部をカキカキします。✍️✍️✍️

```diff_yaml:nextjs.yml
# ...
      - name: Setup Node
        uses: actions/setup-node@v3
        with:
#         ↓ プロジェクトにある package.json の @types/node の値と同じにするといいと思います
-         node-version: "16"
+         node-version: "20"
          cache: ${{ steps.detect-package-manager.outputs.manager }}
# ...
      - name: Build with Next.js
        run: ${{ steps.detect-package-manager.outputs.runner }} next build
-     - name: Static HTML export with Next.js
-       run: ${{ steps.detect-package-manager.outputs.runner }} next export
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v2
        with:
          path: ./out
# ...
```

変更したら、右上の `Commit changes...` からこのファイルをコミットした後に、
コンソールから `git` でプルをします。

```console:めんどくさいですが大事です。
$ git pull   ← プロジェクトをレポジトリと同じファイル構成にします。
```

### どうじゃらほい(ビルドとデプロイがされる様子を見守る)

先ほどコミットした地点で勝手に GitHub Actions が実行してくれています。
GitHub の `▷ Actions` から様子を見てみましょう。

🟠 であれば、まだデプロイ中で、

🔴 であれば、何かしらのエラーが、

🟢 であれば、無事成功となります。

![](https://i.gyazo.com/ffdb06201ebeb418853af85604f06351.png)
~~node-version いじってなくて一回失敗したのはここだけの話~~

## 🟢 だべさ
何も問題がなければ公開までの作業は完了となります。
`https://ユーザー名.github.io/` にアクセスしてみると、テンプレートが表示されています。

![](https://i.gyazo.com/cdddc936085e24bb0496192f5680c423.png)

この後の操作としては、

1. 適宜調べながら `page.tsx` などを編集
2. サイトができたら、`next build`でビルド
3. `next start`でローカルホストに公開
4. `localhost:3000`にアクセスし、バグやCSS完全に理解した現象がないかを確認
5. 問題がなければ `git add -A` の後に `git commit -m '簡潔に作業内容を'`
6. 最後に、`git push -u origin main` でプッシュ。
   → Access Tokens の有効期限が切れていた場合再度作成
7. `https://ユーザー名.github.io/` にアクセスして、実際に問題がないかを確認する

といった感じになります。


## 🔴 なんだが？
おそらくどこかしらで操作を誤ってしまったか、単純にこの記事の情報が古いかのどちらかです。
`▷ Actions` から 🔴 の横の文字をクリックしていくとエラー文っぽいところが出るので、コピペして検索にかけましょう。

![](https://i.gyazo.com/1c7a02485af9a82c7b063a0b0030f9eb.png)

ちなみに上記の `Headers is not defined` の場合 `nextjs.yml` の `node-version` が古いです。
Next 14 のサポートしている Node.js の最小バージョンは `18.17` です

参考：[Next.js 14] [^nextjs]


# おわりに

最初備忘録のつもりで書いてたのに何故かものすごく補足ばかりの記事になってた…

今回使用したもの等を纏めた相関図モドキも作りましたので、ここに置いておきます。

![](https://i.gyazo.com/5edb08adfb8ccdc7bd3b4f66accdab0b.png)

*良い子のみんなはノーコードでサイトを作ろう！*
*世の中には効率が良くてわかりやすくて便利なやつがいっぱいあります！*

*あと、検索するときは最新の情報だけを追うようにしよう！(N敗)*

# 参考(になるかも)
- [今回作ったサイトのGitHub (example-site.github.io)]
- [Deploying: Static Exports - Next.js]
- [NextJS 13.3 からStatic Exportsの方法が変わってた - Zenn]
- [Next.js アプリを GitHub Actions でビルドして GitHub Pages で公開する]
- [自分で作ったWebページをインターネット上に公開しよう！ - Progate]
- [2023年8月版: Next.jsをGitHub ActionsでGitHub Pagesにデプロイする方法]

### 本文に出たやつ

[^vscode]: [Download Visual Studio Code - Mac, Linux, Windows]
[^nodejs]: [Download | Node.js]
[^nodejs_ht]: [Node.jsをインストールする - Qiita]
[^git]: [Git - Downloads]
[^git_ht_w]: [WindowsにGitをインストールする手順(2023年11月更新)]
[^git_ht_m]: [最新の Git を Mac にインストールする方法 - Qiita]
[^github]: [GitHub: Let’s build from here]
[^github_ht]: [GitHubアカウント作成 - Qiita]
[^organization_ht]: [新しい Organization をゼロから作成 - GitHub Enterprise Server 3.10 Docs]
[^create_next_ht]: [create-next-appを用いたNextjsアプリ構築方法 - Qiita]
[^access_token_ht]: [GitHubにPushできない！？GitHubアクセストークン作成を画像で分かりやすく解説 - Qiita]
[^nextjs]: [Next.js 14]


[N/S高等学校 Advent Calendar 2023]: https://qiita.com/advent-calendar/2023/n-s-highschool

[Download Visual Studio Code - Mac, Linux, Windows]: https://code.visualstudio.com/download

[Download | Node.js]: https://nodejs.org/en/download

[Node.jsをインストールする - Qiita]: https://qiita.com/sefoo0104/items/0653c935ea4a4db9dc2b

[Git - Downloads]: https://git-scm.com/downloads

[WindowsにGitをインストールする手順(2023年11月更新)]: https://www.curict.com/item/60/60bfe0e.html

[最新の Git を Mac にインストールする方法 - Qiita]: https://qiita.com/normalsalt/items/f200ba50363ebfd46df0

[GitHub: Let’s build from here]: https://github.com/

[GitHubアカウント作成 - Qiita]: https://qiita.com/Baru_Try/items/e80a765919a35a3c28c7

[新しい Organization をゼロから作成 - GitHub Enterprise Server 3.10 Docs]: https://docs.github.com/ja/enterprise-server@3.10/organizations/collaborating-with-groups-in-organizations/creating-a-new-organization-from-scratch 

[create-next-appを用いたNextjsアプリ構築方法 - Qiita]: https://qiita.com/kaba_san/items/302b8b731e7fbfa56367

[GitHubにPushできない！？GitHubアクセストークン作成を画像で分かりやすく解説 - Qiita]: https://qiita.com/mokio/items/f6c67c8f9af050383fc0

[Next.js 14]: https://nextjs.org/blog/next-14

[今回作ったサイトのGitHub (example-site.github.io)]: (https://github.com/example-site/example-site.github.io)

[Deploying: Static Exports - Next.js]: https://nextjs.org/docs/pages/building-your-application/deploying/static-exports

[NextJS 13.3 からStatic Exportsの方法が変わってた - Zenn]: https://zenn.dev/dev_shun/articles/ace43099ba43ed

[Next.js アプリを GitHub Actions でビルドして GitHub Pages で公開する]: https://maku.blog/p/au8ju6g/

[自分で作ったWebページをインターネット上に公開しよう！ - Progate]: https://prog-8.com/docs/github-pages

[2023年8月版: Next.jsをGitHub ActionsでGitHub Pagesにデプロイする方法]: https://zenn.dev/pino0701/articles/nextjs_github_pages