Next.js 앱을 GitHub 페이지에 게시해야 합니다

최근에 저는 2048 Game의 오픈 소스 버전을 개편하고 이를 Next.js 및 React 18로 마이그레이션하기로 결정했습니다. 기존 게임은 사용자 정의 도메인 없이 GitHub 페이지에 게시되었습니다. Vercel에 배포하려고 고려 중이었지만 지난 3년 동안 축적된 Google의 유기적 트래픽이 손실될 것입니다. 이는 GitHub 페이지에 대한 배포를 실험해야 한다는 의미이며 오늘은 제가 배운 내용을 공유하겠습니다.

전체 기사를 읽기 전에 최종 결과를 보려면 다음을 수행하십시오. 여기에서 확인하세요 .

빠른 소개

저는 GitHub Actions와 GitHub Pages라는 두 가지 GitHub 기능을 사용할 것입니다. 들어본 적이 없다면 빠르게 설명하겠습니다.

GitHub Actions는 프로젝트에서 작업을 수행할 수 있는 작은 워크플로와 같습니다. 그것은 당신이 지시한 일을 자동으로 수행하는 도우미를 갖는 것과 같습니다. 작업을 사용하여 테스트를 실행하거나 품질 확인을 하거나 애플리케이션을 구축할 수 있습니다. 제 경우에는 이 워크플로를 사용하여 배포 파이프라인을 자동화했습니다.

GitHub 페이지 란 무엇입니까? 개발자 및 오픈 소스 프로젝트를 위한 웹 호스팅 옵션처럼 생각하십시오. GitHub 페이지를 사용하여 포트폴리오를 공유하고, 오픈 소스 프로젝트의 웹사이트를 호스팅하거나, 저와 같은 애완동물 프로젝트를 게시할 수 있습니다.

이제 시작해 보겠습니다.

1단계 – 리포지토리용 GitHub 페이지 활성화

Next.js 애플리케이션을 게시하려면 프로젝트 저장소에 대한 GitHub 페이지를 활성화해야 했습니다. 설정 탭(아래 이미지의 1)에서 페이지를 찾은 다음 왼쪽 메뉴에서 페이지를 선택하고(2) 배포 소스를 지정할 수 있는 드롭다운 메뉴를 찾습니다(3).

이제 배포 소스를 GitHub Actions 로 변경해야 합니다.

이제부터 프로젝트에는 전용 페이지가 있습니다. 거기에 콘텐츠를 게시하기만 하면 됩니다.

2단계 – Next.js 빌드 프로세스 구성

Next.js 앱을 배포하기 전에 빌드 출력을 변경하는 것이 중요합니다. 기본적으로 Next.js는 Node.js를 사용하여 애플리케이션을 실행하며 이는 GitHub 페이지와 호환되지 않습니다.

GitHub 페이지는 정적 파일을 호스팅하도록 설계되었습니다. 즉, HTML, CSS, JavaScript(및 기타 정적 파일)만 게시할 수 있습니다. 따라서 Next.js에서 정적 페이지 생성을 활성화해야 합니다.

이렇게 하려면 출력 모드를 next.config.js 내부로 export 도록 변경합니다.

 /** @type {import('next').NextConfig} */ const nextConfig = { output: "export", // <=== enables static exports reactStrictMode: true, }; module.exports = nextConfig;

이제 next build 실행한 후 Next.js는 앱의 정적 자산이 포함된 out 폴더를 생성합니다. 다음 단계에서는 이 디렉터리를 가져와 GitHub 페이지에 업로드하겠습니다.

3단계 - 누락된 이미지 수정

페이지는 도메인의 하위 경로에 게시되며 프로젝트 이름을 하위 경로로 사용합니다. 혼란스럽나요? 예를 들어 내 2048 게임의 URL을 살짝 살펴보겠습니다.

 https://mateuszsokola.github.io/2048-in-react/

Github는 내 사용자를 위해 mateuszsokola(내 사용자 이름) 라는 전용 하위 도메인을 만들었습니다. 하지만 프로젝트는 하위 경로 아래에 게시됩니다. 제 경우에는 /2048-in-react 입니다. 불행하게도 이로 인해 이미지와 스타일이 누락되는 문제가 발생합니다.

기본적으로 Next.js는 모든 정적 자산을 도메인에 매핑합니다. 즉, favicon.ico 파일은 mateuszsokola.github.io/favicon.ico 대신 mateuszsokola.github.io/2048-in-react/favicon.icon 로 확인됩니다.

이 문제를 해결하려면 next.config.js 파일 내에 basePath 추가하여 경로 접두사를 설정할 수 있습니다.

 /** @type {import('next').NextConfig} */ const nextConfig = { basePath: "/2048-in-react", // <=== here it is output: "export", reactStrictMode: true, }; module.exports = nextConfig;

제 경우에는 프로젝트 이름이 /2048-in-react 2048-in-react 입니다.
프로젝트 디렉터리 시작 부분에 ( / ) 를 포함해야 합니다 .

4단계 - Github 작업 생성

Next.js는 GitHub 페이지에 게시할 수 있는 배포 아티팩트를 생성하고 있습니다. 이제 Github Actions를 설정하여 게시할 차례입니다. 재사용성을 촉진하기 위해 두 가지 별도의 작업으로 배포를 결정했습니다.

setup-node 작업은 Node.js를 설정하고 모든 종속성을 설치합니다. Node.js 설정에 대한 독립 실행형 작업이 있으면 다른 파이프라인에서 이를 재사용할 수 있습니다. 예를 들어, 다음을 실행하는 파이프라인이 있습니다. 코드 린터 그리고 테스트 . 아마도 당신은 하나 이상의 작업을 원할 것입니다.

publish 작업은 코드를 main 브랜치에 병합할 때마다 Next.js 아티팩트를 빌드하고 GitHub 페이지에 게시합니다.

먼저 setup-node 작업을 설명하겠습니다. 코드는 다음과 같습니다.

 # File: .github/workflows/setup-node/action.yml name: setup-node description: "Setup Node.js ⚙️ - Cache dependencies ⚡ - Install dependencies 🔧" runs: using: "composite" steps: - name: Setup Node.js ⚙️ uses: actions/setup-node@v4 with: node-version: 20 - name: Cache dependencies ⚡ id: cache_dependencies uses: actions/cache@v3 with: path: node_modules key: node-modules-${{ hashFiles('package-lock.json') }} - name: Install dependencies 🔧 shell: bash if: steps.cache_dependencies.outputs.cache-hit != 'true' run: npm ci

중요 : 프로젝트의 .github/workflows/setup-node 디렉터리에 이 파일을 생성하세요. 이름을 action.yml 로 지정하세요.

이 스니펫의 기능은 무엇인가요?

1. composite 동작을 생성합니다. composite 작업을 사용하면 여러 워크플로 단계를 단일 작업으로 묶을 수 있습니다. 명확하지 않은 경우 두 번째 작업을 시작하면 이해하게 될 것입니다.

2. Node.js 20을 사용하여 새로운 빌드 환경을 만들고 프로젝트 종속성을 설치합니다.

이는 setup-node 작업의 가장 중요한 부분입니다. 이제 publish 작업으로 넘어가겠습니다.

 # File: .github/workflows/publish.yml name: publish-to-github-pages on: push: branches: - main permissions: contents: read pages: write id-token: write concurrency: group: "pages" cancel-in-progress: false jobs: build: runs-on: ubuntu-latest steps: - name: Checkout 🛎️ uses: actions/checkout@v4 - name: Setup Node.js ⚙️ - Cache dependencies ⚡ - Install dependencies 🔧 uses: ./.github/workflows/setup-node - name: Setup Pages ⚙️ uses: actions/configure-pages@v4 with: static_site_generator: next - name: Build with Next.js 🏗️ run: npx next build - name: Upload artifact 📡 uses: actions/upload-pages-artifact@v3 with: path: ./out deploy: environment: name: github-pages url: ${{ steps.deployment.outputs.page_url }} runs-on: ubuntu-latest needs: build steps: - name: Publish to GitHub Pages 🚀 id: deployment uses: actions/deploy-pages@v4

프로젝트의 .github/workflows 디렉터리에 이 파일을 만듭니다. 원하는 대로 파일 이름을 지정할 수 있습니다. 저는 publish.yml 이라고 불렀습니다.

그것은 무엇을 하는가?

1. 이 작업은 새 코드가 main 분기에 푸시되거나 병합될 때마다 트리거됩니다.

2. setup-node 작업을 사용하여 환경을 설정합니다. 이전 작업에서 만든 composite 작업입니다. 이제 다른 작업에 composite 작업을 포함하는 방법을 알았습니다.

3. 작업에는 두 단계가 있습니다. 첫 번째 단계에서는 Next.js 앱이 구축됩니다. 두 번째 단계에서는 첫 번째 단계의 아티팩트가 GitHub 페이지에 업로드됩니다.

이는 배포 파이프라인의 가장 중요한 측면입니다. 모든 GitHub 페이지 배포에 대해 변경되지 않은 권한 및 동시성 설정을 건너뛰었습니다.

이제 작업을 사용할 준비가 되었습니다.

커밋 및 푸시

변경 사항을 main 브랜치에 커밋하고 푸시한 후 GitHub는 자동으로 GitHub 페이지에 배포를 시작합니다.

프로세스를 검사하려면 작업 탭(아래 이미지의 1)으로 이동하고 왼쪽 메뉴에서 게시-github-pages 작업을 선택합니다(2) . 화면에 모든 배포가 표시됩니다( 워크플로 라고 함).

이제 해당 워크플로 중 첫 번째 워크플로를 선택하면 2단계 배포가 표시됩니다. 배포 단계에서는 GitHub 페이지에서 웹사이트 링크를 찾을 수 있습니다.

결론

Github 페이지는 수백만 건의 조회수가 있는 웹사이트를 호스팅하기에 충분하지 않습니다. 하지만 포트폴리오나 오픈 소스 프로젝트를 위한 웹사이트를 호스팅하는 데는 완벽한 선택입니다.

Vercel과 같이 당사 웹사이트를 호스팅할 수 있는 무료 옵션이 많이 있지만 저는 대안을 보여드리고 싶었습니다. GitHub 페이지는 개발자를 위해 만들어졌으므로 모든 개발자가 이에 익숙해져야 한다고 생각합니다.

이 글이 도움이 되셨다면 SNS에 공유해주세요.

그리고 애플리케이션을 어디에 배포합니까? 항상 Vercel인가요?

React 18 및 Next.js 배우기

React나 Next.js에 자신이 없다고 느끼시나요? Udemy의 온라인 강좌에 참여하세요! 완전한 기능을 갖춘 2048 게임을 만들어 React를 시작하는 데 도움을 드리겠습니다. 저는 게임을 만들면 학습이 더 재미있어지고 친구들에게 보여줄 멋진 것을 갖게 될 것이라고 믿습니다.

👇👇👇👇

🧑‍🎓 가입 Udemy의 React 18 및 Next.js 과정 – 이번주에만 80% 할인됩니다.