🚀 Next.js 워크플로우 완전 정복

🚀 Next.js 워크플로우 완전 정복

 

Next.js 프로젝트에서 효율적인 CI/CD를 위한 GitHub Actions 워크플로우 설정

 

📌 목차

1️⃣ Next.js에서 CI/CD를 도입해야 하는 이유

2️⃣ Next.js 워크플로우 기본 구조

3️⃣ 주요 구성 요소 (on, jobs, steps, needs 등)

4️⃣ Next.js CI/CD 자동화 설정 예제

5️⃣ 배포 자동화를 위한 추가 최적화 전략

6️⃣ 결론

1️⃣ Next.js에서 CI/CD를 도입해야 하는 이유

 

Next.js 프로젝트에서는 정적 생성(SSG), 서버 사이드 렌더링(SSR), API Routes, Image Optimization 등

여러 가지 기능이 존재하기 때문에 배포 자동화와 성능 최적화가 매우 중요해요.

CI/CD를 통해 🚀

✅ 자동으로 빌드 & 배포해서 실수를 줄이고,

✅ 코드 변경 사항을 빠르게 검증해서 안전한 배포를 가능하게 만들 수 있어요.

 

✅ CI/CD 없이 배포할 경우?

❌ 로컬에서만 동작하는 코드가 있을 수 있음

❌ 배포 시 환경 변수가 누락될 가능성 높음

❌ 정적 페이지 & 서버 사이드 페이지 캐싱 문제 발생

 

이제 Next.js의 워크플로우를 어떻게 설정하면 좋을지 살펴보자! 🎯

2️⃣ Next.js 워크플로우 기본 구조

 

Next.js 프로젝트에서 CI/CD를 자동화하기 위해 보통 GitHub Actions를 활용해요.

GitHub Actions는 YAML 파일을 이용해서 워크플로우를 정의하고 실행하는데,

기본 구조는 다음과 같아요.

name: Next.js CI/CD

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Repository
        uses: actions/checkout@v3

      - name: Set up Node.js
        uses: actions/setup-node@v3
        with:
          node-version: 18

      - name: Install Dependencies
        run: npm ci

      - name: Build Project
        run: npm run build

📌 위 코드의 구조를 보면?

✅ on: 어떤 이벤트가 발생하면 워크플로우를 실행할지 설정

✅ jobs: 실행할 작업들을 정의

✅ steps: 한 개의 작업(job) 안에서 단계별로 실행할 명령어

 

이제 각각의 구성 요소를 자세히 살펴보자! 🧐

3️⃣ 주요 구성 요소 (on, jobs, steps, needs 등)

 

✔️ on: 워크플로우 실행 조건

 

on 키워드는 GitHub Actions에서 특정 이벤트가 발생했을 때 실행되는 조건을 정의해요.

Next.js에서는 주로 push, pull_request, workflow_dispatch 등을 사용해요.

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main
  workflow_dispatch:  # 수동 실행

✅ 이렇게 설정하면?

✔️ main 브랜치에 push 또는 PR이 발생하면 실행

✔️ workflow_dispatch 옵션을 추가하면 GitHub Actions에서 직접 실행 가능

✔️ jobs: 실행할 작업 그룹

 

jobs 안에는 여러 개의 job을 정의할 수 있어요.

예를 들어, 빌드 → 테스트 → 배포 순서로 실행하고 싶다면 각각의 job을 정의할 수 있어요.

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Repository
        uses: actions/checkout@v3

      - name: Install Dependencies
        run: npm ci

      - name: Build Next.js
        run: npm run build

✅ 이렇게 하면?

✔️ ubuntu-latest 환경에서 실행

✔️ npm ci로 의존성 설치 후 npm run build 실행

✔️ steps: 각 작업에서 실행할 단계

 

각 job에는 여러 개의 steps(단계)가 들어가요.

GitHub Actions에서 제공하는 기본 액션(uses)을 사용하거나 직접 명령어(run)를 실행할 수도 있어요.

steps:
  - name: Checkout Repository
    uses: actions/checkout@v3

  - name: Set up Node.js
    uses: actions/setup-node@v3
    with:
      node-version: 18

  - name: Install Dependencies
    run: npm ci

✅ 이렇게 하면?

✔️ checkout@v3 → 레포지토리 코드 가져오기

✔️ setup-node@v3 → Node.js 18 버전 설정

✔️ npm ci → 패키지 설치

✔️ needs: 워크플로우 실행 순서 지정

 

needs를 사용하면 특정 job이 완료된 후에 다른 job이 실행되도록 할 수 있어요.

예를 들어, 빌드가 끝나야 배포를 할 수 있다면 아래처럼 설정할 수 있어요.

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Install Dependencies
        run: npm ci
      - name: Build Next.js
        run: npm run build

  deploy:
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy Application
        run: echo "배포 진행 중..."

✅ 이렇게 하면?

✔️ build 작업이 끝난 후에만 deploy 실행!

4️⃣ Next.js CI/CD 자동화 설정 예제

 

빌드 + 테스트 + 배포까지 자동화된 Next.js CI/CD 설정을 만들어보자!

name: Next.js CI/CD Pipeline

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Repository
        uses: actions/checkout@v3
      - name: Install Dependencies
        run: npm ci
      - name: Build Next.js
        run: npm run build

  test:
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Run Tests
        run: npm test

  deploy:
    runs-on: ubuntu-latest
    needs: test
    steps:
      - name: Deploy Application
        run: echo "배포 진행 중..."

📌 이렇게 하면?

1️⃣ build → Next.js 애플리케이션 빌드

2️⃣ test → 빌드 완료 후 테스트 실행

3️⃣ deploy → 테스트 완료 후 배포 진행

5️⃣ 배포 자동화를 위한 추가 최적화 전략

 

배포를 안정적으로 하기 위해 다음과 같은 추가 설정을 고려할 수 있어요.

 

✅ 환경 변수 설정

 

Next.js에서 .env 파일을 CI/CD에서 사용하려면 GitHub Actions의 secrets 기능을 활용해야 해요.

- name: Set Environment Variables
  run: echo "NEXT_PUBLIC_API_KEY=${{ secrets.API_KEY }}" >> .env

✅ Vercel을 이용한 자동 배포

 

Next.js는 Vercel과 궁합이 좋아요! Vercel을 이용하면 배포를 쉽게 자동화할 수 있어요.

Vercel CLI를 이용해서 아래처럼 설정하면 코드가 푸시될 때마다 자동으로 배포 가능!

- name: Deploy to Vercel
  run: vercel --prod --token=${{ secrets.VERCEL_TOKEN }}

🎯 결론: Next.js CI/CD 자동화 마스터!

 

✔️ CI/CD 워크플로우 기본 구조를 이해하고 실행 순서를 제어할 수 있음

✔️ 테스트 & 배포 자동화를 통해 안정적인 프로젝트 운영 가능

✔️ Vercel과 연동하여 손쉽게 배포할 수 있음

 

💡 이제 Next.js 프로젝트에서도 CI/CD를 마스터하고,

자동으로 배포되는 멋진 개발 환경을 구축해보자! 🚀

 

🌷 전설의 개발자가 되어봅시당! 🌷