안드로이드 태블릿에서 github page에 Next.js 프로젝트 배포하기 #

들어가기 앞서 #

이 문서는 안드로이드 태블릿에서 만든 Next.js 프로젝트를 Github에 배포하는 방법에 대해 설명하는 문서입니다.
태블릿에 Node.js가 설치되어있고 Next.js 프로젝트를 구성하여 프로젝트를 실행해본 상태에서 진행합니다.
Github 계정은 깃허브 공식 홈페이지에서 만드실 수 있습니다.

github 저장소 생성 #

github.io 란? #

GitHub Pages는 **GitHub 저장소의 파일(HTML/CSS/JS 등)**을 그대로 웹사이트로 배포해주는 기능입니다.
그중에서도 github.io는 GitHub Pages로 만들어지는 기본 도메인이고, 보통 아래 두 종류가 있어요.

• User/Organization 사이트: https://[계정명].github.io/
  → 저장소 이름이 반드시 [계정명].github.io 여야 함
• Project 사이트: https://[계정명].github.io/[repo]/
  → 일반 저장소에서도 가능

즉, 블로그나 포트폴리오를 “루트 도메인”으로 깔끔하게 쓰려면 User 사이트 방식이 가장 깔끔합니다.

---

[계정명].github.io를 만들어보자 #

아래 순서대로 하면 됩니다.

1) GitHub에서 새 저장소 만들기 #

1. GitHub 로그인

2. 우측 상단 + 버튼 → New repository 클릭

3. Repository name에 아래처럼 입력

   • [계정명].github.io (계정명과 정확히 일치해야 함)

4. 공개 설정은 보통 Public 추천

5. (선택) Add a README file 체크해제

6. Create repository 클릭

---

2) Next.js 프로젝트를 export 모드로 설정 하고 git remote 추가 #

여기서는 **Next.js 프로젝트를 정적 사이트(export 모드)**로 설정한 뒤, GitHub Pages에서 제공하는
rxalloc.github.io 저장소와 연결하는 과정을 진행합니다.

---

2-1) Next.js를 export 모드로 설정하기 #

GitHub Pages는 서버가 없는 정적 호스팅이기 때문에 Next.js를 반드시 export 모드로 설정해야 합니다.

프로젝트 루트에 있는 next.config.js 또는 next.config.mjs 파일을 아래처럼 수정합니다.

jsCopy
/** @type {import('next').NextConfig} */
const nextConfig = {
  output: "export", // ✅ 정적 사이트로 빌드
  images: {
    unoptimized: true, // ✅ next/image 서버 최적화 비활성화 (필수)
  },
};

module.exports = nextConfig;

---

2-2) 정적 빌드 결과 확인 #

설정이 끝났다면 프로젝트를 빌드합니다.

bashCopy
npm run build

빌드가 성공하면 프로젝트 루트에 out/ 폴더가 생성됩니다.
이 폴더 안의 파일들이 GitHub Pages에 그대로 배포될 정적 결과물입니다.

---

2-3) Git 저장소 초기화 #

아래 명령으로 초기화합니다.

bashCopy
git init
git add .
git commit -m "init"

---

2-4) rxalloc.github.io 저장소를 remote로 추가 #

GitHub에서 미리 생성해 둔 rxalloc.github.io 저장소와 연결합니다.

bashCopy
git branch -M main
git remote add origin https://github.com/rxalloc/rxalloc.github.io.git
git push -u origin main

정상적으로 푸시되면 GitHub 저장소에 코드가 업로드됩니다.

---

3) Git으로 커밋하고 푸시하기 #

터미널에서 Next.js 폴더로 이동 후:

bashCopy
git init
git add .
git commit -m "init"
git branch -M main
git remote add origin https://github.com/[계정명]/[계정명].github.io.git
git push -u origin main

정상적으로 프로젝트가 github에 올라갔다면 아래와 같이 해당 레포지토리 페이지에서 소스코드를 확인하실 수 있습니다.

---

4) gh-pages를 사용해서 배포하기 #

gh-pages는 빌드 결과물(out/)만 별도 브랜치(gh-pages)로 배포해주는 도구입니다.
소스 코드와 배포 결과를 분리할 수 있어 유지보수에 가장 깔끔한 방식입니다.

---

4-1) gh-pages 설치 #

프로젝트 루트에서 아래 명령을 실행합니다.

bashCopy
npm install --save-dev gh-pages

---

4-2) package.json 스크립트 추가 #

package.json에 아래 스크립트를 추가합니다.

jsonCopy
{
  "scripts": {
    "build": "next build",
    "deploy": "gh-pages -d out"
  }
}

---

4-4) 빌드 & 배포 실행 #

아래 명령 한 줄로 빌드 + gh-pages 브랜치 배포가 완료됩니다.

bashCopy
npm run build
npm run deploy

정상 동작 시:

• gh-pages 브랜치가 자동 생성됨
• out/ 폴더의 내용만 gh-pages 브랜치에 커밋됨

---

4-5) GitHub Pages 브랜치 설정 #

1. GitHub 저장소 → Settings

2. 좌측 메뉴 → Pages

3. Build and deployment

   • Source: Deploy from a branch
   • Branch: gh-pages / (root)

4. 저장

---

4-6) 접속 확인 #

배포가 완료되면 아래 주소로 접속합니다.

plainCopy
https://[계정명].github.io

정상이라면 out/index.html 기준의 사이트가 표시됩니다.

RxAlloc Blog

---

4-7) CSS파일이 제대로 불러오지 않는다면 #

.nojekyll 파일을 추가해주어야합니다.
아래의 이미지를 참고하여 .nokekyll 파일을 추가해주시면 됩니다.

---

참고 #

• 이후 배포는 npm run deploy 한 줄이면 끝
• 소스 브랜치(main)와 배포 브랜치(gh-pages)가 분리되어 히스토리가 깔끔함
• GitHub Actions 없이도 안정적으로 사용 가능