↓ Skip to main content
Kre³’s Blog
Notes on Deploying Next.js Static Pages to GitHub Pages

Notes on Deploying Next.js Static Pages to GitHub Pages

·395 words·2 mins·
Learning
Kre³
Author
Kre³
Doing code and art with ❤
Table of Contents
The English version is translated by AI (Gemini 2.5 Pro Preview). If you want to view the original content, please switch to Chinese version.

My personal homepage www.ohmykreee.top is reborn, go check it out!

(Why does this copy sound like a marketing account?)

Zero, Some Nonsense
#

Originally, according to convention, after finishing a project, I should write an article about what I learned in this project. But because I was lazy this time (I’m not hiding it, come and bite me~~), this time I will only write about a few things to pay attention to if you want to render a Next.js project into a static web page and publish it on GitHub Pages.

(Actually, the knowledge points are a bit miscellaneous, and they are problems related to a specific library, which has little reference value. If you want to learn together, you can consider looking at the project source code directly, anyway, the whole project is not very large.)

One, Next.js and Static Web Page Rendering
#

Reference: Static HTML Export - Next.js

Using the command next build && next export can render the entire project into static HTML files and output them to the out folder. No extra configuration is required by default.

If you want to further simplify the operation, you can also edit the build command in package.json:

"scripts": {
  "build": "next build && next export"
}

Then run npm run build.

Two, Jekyll and Underscores
#

Reference: Bypassing Jekyll on GitHub Pages - GitHub Blog

In fact, GitHub Pages is not a simple static web page providing service, but a Jekyll service (in the official words: GitHub Pages is powered by Jekyll.) And Jekyll will ignore all folders and files starting with _ before generating the final website.

But what a coincidence: in the files generated by Next.js, some key files are stored in the _next folder (I think it’s intentional), which causes the entire web page to crash if the generated files are directly pushed to GitHub Pages.

The solution is very simple, just put an empty file named .nojekyll in the root directory, so that GitHub Pages will force skip the processing of Jekyll when generating the final web page.

If you use GitHub actions, you can write it like this in the workflow file:

      - name: Build static page
        run: |
          npm run build
          touch ./out/.nojekyll