Next.js 프로젝트 Github Pages 배포

이전에 React로 이력서 페이지를 만들어 github에 배포한 적이 있다.

github을 이용한 배포는 처음이었기에 당시에도 시간이 꽤 걸리기는 했지만 관련 정보가 많기도 했고 단순히 명령어를 입력하는 터미널을 바꾼 것으로 오류가 해결되었기 때문에 배포가 어렵지는 않았다.

하지만 next.js 배포는 더 어려웠다. next.js 배포 방법이 최근에 살짝 변경된 모양이었는데, 그 이유 때문에 검색을 해서 상위권에 올라와 있던 포스팅을 따라 해서는 배포가 정상적으로 진행되지 않았다.

혼자 에러 코드 관련해서 찾아보고 여러 방법으로 배포를 진행해 본 결과 다행히도 웹 사이트 배포에 성공했고, 이후의 웹 사이트 배포에 참고하기 위해 실제로 배포에 사용한 방법을 정리해 보기로 했다.

 

`gh-pages` 패키지 설치

우선 gh-pages 패키지를 설치한다. 깃헙 페이지에 배포하는 것을 도와주는 패키지이다.

yarn add -D gh-pages
npm i --save-dev gh-pages

 

 

package.json에 필요한 코드 추가

package.json

  "homepage": "https://깃헙ID.github.io/레파지토리명",
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "next lint",
    "deploy": "touch out/.nojekyll && gh-pages -d out --dotfiles"
  }

package.json 내부에 위와 같이 homepage 주소를 지정하고 스크립트를 지정해 준다.

 

"homepage" 속성은 React 애플리케이션을 GitHub Pages 또는 다른 정적 호스팅 서비스에 배포할 때 사용되는 설정으로, GitHub Pages에 배포될 경우 애플리케이션의 홈페이지 URL을 지정할 수 있다. 

이곳에 인터넷에 배포될 나의 도메인 주소를 입력한다.

"scripts" 속성은 프로젝트에서 사용할 수 있는 여러 명령어를 정의해 두는 곳이다. 개발, 빌드, 실행, 테스트, 배포 등과 관련된 명령어를 설정한다. 이러한 스크립트들을 사용하면 간단한 명령어로 프로젝트를 빌드하고 실행하며, 린트를 실행하거나 배포할 수 있다. 

• `"dev": "next dev"`: 개발 서버를 실행하는 명령어. next dev 명령어는 Next.js 애플리케이션을 개발 모드로 실행한다.
• `"build": "next build"`: 프로덕션용으로 애플리케이션을 빌드하는 명령어. next build 명령어는 애플리케이션을 최적화하고 번들링 하여 빌드한다.
• `"start": "next start"`: 빌드된 애플리케이션을 실행하는 명령어. next start 명령어는 빌드된 애플리케이션을 서버로 실행한다.
• `"lint": "next lint"`: 코드 린트(코드의 오류나 버그 등을 미리 점검하기 위해 사용하는 툴)를 실행하는 명령어. next lint 명령어는 코드 스타일과 품질에 대한 체크를 수행한다.
• `"deploy": "touch out/.nojekyll && gh-pages -d out --dotfiles"`: 배포를 위한 명령어. gh-pages를 사용하여 out 디렉토리의 내용을 GitHub Pages에 배포하고, .nojekyll 파일을 생성한다.

 

next.config.js 에 필요한 코드 추가

next.config.js

/** @type {import('next').NextConfig} */
const nextConfig = {
  reactStrictMode: true,
  output: "export",	//추가
};

module.exports = nextConfig;

위와 같이 `output: "export",`를 추가해 주면 된다.

Static Export를 활성화하기 위해 내부에서 output 모드를 변경하는 부분이다. 

 

바로 이 부분에서 오래 헤맸다.

위의 `output: "export",`코드를 작성해주지 않았거나, package.json 내부에 export가 들어간 script를 추가하면 아래와 같은 에러가 뜬다.

The "next export" command has been removed in favor of "output: export" in next.config.js.

 

구글에 next.js github 배포를 검색하면 package.json에 `"build": "next build && next export",`와 같은 스크립트 코드를 작성하라는 방법이 많이 뜨는데, 지금은 이렇게 작성하면 에러가 뜬다. 

아래에 Next.js의 Static Export(정적 내보내기)에 대한 공식문서 설명이 있다.

Deploying: Static Exports | Next.js

 

 

빌드

위의 사항까지 다 마치고 나서 작성한 코드를 commit하고 push 해주었다.

그 후에 powershell에 아래 코드를 입력하여 빌드했다.

npm run build

여기까지 하면 코드를 업로드한 깃허브 레파지토리 > Setting > Pages에 사이트 url이 생성되고 배포된다.

하지만 url에 들어가보면 레파지토리의 Readme.md 화면만 뜨고, 정상적으로 배포가 이루어지지 않았음을 알 수 있다.

 

조금만 더 밑을 내려 Build and deployment 항목을 살펴보면 아래와 같이 Branch가 `main`으로 고정되고, 옵션으로도 None 하나밖에 뜨지 않음을 확인할 수 있다.

사이트를 배포하기 위해서는 Branch를 gh-pages로 변경해 줘야 한다.

 

배포

Branch에 gh-pages 옵션을 생성하기 위해서는 빌드한 파일을 배포까지 해주어야 한다.

npm run deploy

`Published` 문구가 뜨고 확인하면 아래와 같이 gh-pages 옵션이 잘 뜬다.

이제 옵션을 아래처럼 설정하고 Save 해주면 된다. 

 

 

화면에 바로 반영되지 않고 10분 정도 기다려야 한다고 한다.

그 결과 화면은 잘 떴는데, CSS 부분이 싹 사라져 있다.

 

CSS 적용하기 (assetPrefix 경로 수정)

next.config.js

/** @type {import('next').NextConfig} */
const nextConfig = {
  reactStrictMode: true,
  output: "export",
  //아래 코드 추가
  assetPrefix:
    process.env.NODE_ENV === "production"
      ? "https://깃헙ID.github.io/레파지토리명"
      : "",
};

module.exports = nextConfig;

assetPrefix는 Next.js 프로젝트에서 정적 자원(이미지, CSS 등)이 호스팅 되는 경로를 지정하는 설정이다.
기본적으로 Next.js는 정적 자원을 현재 도메인의 루트에서 가져오도록 구성되어 있지만, assetPrefix를 사용하면 정적 자원을 다른 도메인 또는 서브디렉터리에서 가져올 수 있다.

 

 

정상적으로 배포가 완료되었다.

 

 

배포한 사이트

심플 룰렛

👇 추후 하위도메인 대신 메인 도메인/roulette 페이지를 만들어 다시 배포했다. 

심플 룰렛

---

참고

 

아래 블로그+스택오버플로우 글들을 참고했다.

 

 

Next.js 이전 버전 글들

Next.js Github Pages 가장 쉽게 배포하기

Next.js Github Pages에 배포하기

 

CSS 누락 해결하기

Nextjs 프로젝트 Github Pages로 배포하기

 

Next.js 최신 버전 글들 ( `output: "export",` 관련 내용 서술)

[Next.js] 개인 프로젝트 11에서 14로 마이그레이션 과정

Github Pages로 Next 호스팅

 

스택오버플로우

While deploying nextjs app throwing error: The "next export" command has been removed in favor of "output: export" in next.confi