외부 호스팅 배포

Vercel은 Next.js를 만든 회사가 운영하며 프레임워크의 기능과 긴밀하게 통합된 배포 플랫폼입니다. 하지만 특정한 요구사항이나 기존 인프라와의 통합 때문에 다른 호스팅 플랫폼에 Next.js 앱을 배포해야 하는 경우도 있습니다. 이 글에서는 Vercel이 아닌 여러 호스팅 플랫폼에 Next.js 애플리케이션을 배포하는 주요 방법과, 플랫폼별 특징과 고려할 점을 알아봅니다.

다양한 호스팅 옵션

Next.js는 서버 사이드 렌더링(SSR), 정적 사이트 생성(SSG), Route Handler 같은 서버 측 처리 등 여러 실행 방식을 지원하므로, 호스팅 플랫폼은 이 기능들을 얼마나 잘 지원하는지에 따라 고릅니다. Netlify와 Amplify는 관리형 어댑터의 예이고, EC2, Cloud Run, Heroku는 Node.js 서버를 직접 실행할 수 있는 환경, GitHub Pages와 S3는 정적 호스팅의 예입니다. Netlify처럼 여러 방식을 함께 제공하는 플랫폼도 있습니다.

위 표는 관리형 어댑터, 직접 운영하는 Node.js 서버, 정적 내보내기를 비교합니다. 같은 소스라도 서버가 실행되는 위치와 지원되는 기능, 직접 맡아야 하는 운영 범위가 달라집니다. 관리형 어댑터는 정적 자산과 플랫폼용 서버리스 함수를 만들어 내며, 쓰는 Next.js 버전과 기능을 지원하는지가 선택 기준입니다. 직접 Node.js를 운영하면 Next.js 서버와 정적 자산을 그대로 실행하지만, 프로세스, TLS, 로그, 확장을 직접 운영해야 합니다. 정적 내보내기는 out 디렉터리의 HTML, JS, CSS만 만들므로, 요청할 때 서버 실행이 필요 없는 기능에만 알맞습니다. 표의 설명처럼 정적 호스팅에는 서버 액션이나 요청별 서버 렌더링을 그대로 배포할 수 없으며, 브라우저에서 호출하는 외부 API는 별도의 서비스입니다.

지원하는 기능을 먼저 확인한 뒤, CI/CD의 편의성과 비용 구조를 비교합니다.

Netlify에 배포하기

Netlify는 Vercel과 비슷한 기능을 제공하는 서버리스 기반의 배포 플랫폼으로, CI/CD 통합, 글로벌 CDN, 자동 SSL 등이 장점입니다. 배포 방법은 저장소를 연결해 푸시할 때마다 Netlify가 빌드하게 하는 Git 연동과, Netlify CLI로 직접 배포하는 방법 두 가지입니다. 어느 쪽이든 Next.js 프로젝트는 Netlify가 자동으로 감지하므로, 설정 파일은 모노레포처럼 기본값이 맞지 않을 때만 고칩니다. 아래에서는 CLI 준비, 자동 감지와 설정 파일, 배포 순서로 봅니다.

Netlify CLI 설치 및 프로젝트 설정

먼저 Netlify CLI를 설치합니다. CLI는 프로젝트마다 넣는 의존성이 아니라 터미널에서 netlify 명령으로 쓰는 도구입니다. 그래서 아래 명령은 -g(Yarn은 global)를 붙여 전역에 설치하며, 프로젝트의 package.json에는 아무것도 추가되지 않습니다. 지금의 Netlify CLI 27은 Node.js 22.13 이상을 요구하므로, 그보다 낮은 Node.js를 쓰고 있다면 먼저 Node.js를 올립니다.

npm install -g netlify-cli
# 또는
yarn global add netlify-cli

위의 Yarn 명령은 Yarn Classic의 전역 설치 문법입니다. 쓰는 패키지 관리자에 맞는 설치 명령을 고른 뒤, 프로젝트 루트에서 Netlify에 로그인하고 초기화합니다.

netlify login
netlify init

netlify init 명령은 Netlify 프로젝트를 설정하고, 빌드와 배포 설정을 정의하는 netlify.toml 파일을 만들도록 돕습니다.

Git 연동과 자동 감지

Netlify는 Next.js 13.5 이상을 OpenNext 기반의 어댑터로 자동 감지합니다. 일반적인 프로젝트는 Git 저장소를 연결하고 빌드 명령을 npm run build로 두면, SSR, Route Handler, 이미지 최적화에 필요한 런타임을 함께 구성합니다. 프레임워크가 제안하는 빌드와 publish 설정을 먼저 쓰며, .next/standalone을 일반 정적 사이트처럼 업로드하거나 필요 없이 어댑터 버전을 손으로 고정하지 않습니다. 모노레포의 기본 디렉터리나 별도의 빌드 명령이 필요할 때만 netlify.toml에 그 값을 추가합니다.

[build]
  base = "apps/web"
  command = "npm run build"

base는 Netlify가 빌드를 시작할 폴더이고, command는 그 폴더에서 실행할 빌드 명령입니다. 이 예시는 Next.js 앱이 저장소의 apps/web에 있을 때만 필요하며, publish 값은 Netlify가 Next.js를 감지해 정한 값을 그대로 쓰도록 적지 않았습니다.

배포하기

Netlify 대시보드에서 Git 저장소를 연동해 자동 배포를 설정하거나, CLI로 손수 배포할 수 있습니다. 권장하는 방식은 Git 연동입니다. Netlify 대시보드에서 Add new project를 누르고 Import an existing project를 고른 뒤, GitHub, GitLab, Bitbucket 같은 Git 서비스에서 Next.js 프로젝트의 저장소를 연결합니다. Netlify가 프로젝트를 분석해 빌드 설정을 제안하면 확인한 뒤 배포하며, 모노레포처럼 직접 만든 netlify.toml이 있다면 그 설정도 함께 확인합니다.

CLI로 손수 배포할 때는 다음 명령을 씁니다.

npm run build # 로컬에서 Next.js 빌드
netlify deploy --prod # 프로덕션 환경으로 배포 (이전에 netlify init으로 프로젝트 연결 필요)

지금의 Netlify CLI에서 deploy는 기본적으로 Netlify 빌드를 실행합니다. 위의 첫 명령은 별도로 로컬에서 Next.js 빌드를 확인하는 것이므로, 이어서 실행하면 빌드가 두 번 될 수 있습니다.

AWS에 배포하기 (Amplify 또는 EC2)

AWS는 여러 배포 서비스를 제공하며, Next.js 애플리케이션의 규모와 복잡도에 따라 선택지가 달라집니다. 이 절에서는 성격이 반대인 두 서비스를 비교합니다. Amplify는 저장소를 연결하면 빌드와 SSR 실행 환경을 AWS가 맡는 관리형 서비스이고, EC2는 가상 서버를 빌려 Node.js 서버를 직접 운영하는 방식입니다. 앞의 것은 운영 부담이 적은 대신 지원하는 Next.js 버전과 기능이 정해져 있고, 뒤의 것은 그런 제약이 적은 대신 서버 운영을 모두 맡아야 합니다.

AWS Amplify (지원 범위를 확인하는 관리형 배포)

AWS Amplify는 프론트엔드 웹과 모바일 앱을 위한 통합 개발 플랫폼으로, Next.js 앱을 호스팅하고 인증, API, 데이터베이스 같은 백엔드 서비스를 통합할 수 있습니다. 다만 관리형 SSR이 지원하는 버전과 기능 범위가 Next.js의 최신 버전을 곧바로 따라가지는 않습니다.

지금 AWS의 공식 지원표는 Hosting compute의 Next.js 지원을 12부터 15까지로 안내합니다. 이전 Classic의 Next.js 11 지원과는 구분하며, 이 교재의 Next.js 16 프로젝트가 호환된다고 가정하지 말고 배포하기 전에 지원표를 다시 확인합니다. Next.js 16의 관리형 SSR 지원이 확인되기 전에는 다음 콘솔 절차를 그대로 적용하지 말고, EC2나 컨테이너 같은 자체 Node.js 호스팅이나 아래의 정적 내보내기를 고릅니다.

지원이 확인된 경우의 절차는 다음과 같습니다. AWS Amplify Hosting 콘솔에서 새 앱을 만들고 GitHub, GitLab, Bitbucket 같은 Git 공급자를 연결한 뒤, 배포할 저장소와 브랜치를 고르고 Amplify가 감지한 Next.js 빌드 설정을 확인합니다. SSR 앱의 .next 안의 파일을 일반 정적 산출물처럼 직접 지정하지 않습니다. 콘솔에서 빌드에 필요한 환경 변수를 등록하되, SSR 코드에서 쓸 값은 Amplify가 서버 환경 변수를 전달하는 절차도 확인한 뒤 첫 배포를 실행합니다. 콘솔의 빌드 환경 값이 모두 SSR 런타임에 저절로 제공되지는 않습니다. 이후 연결한 브랜치에 커밋이 들어오면 빌드와 배포가 자동으로 진행됩니다. 정적 내보내기만 배포한다면 output: 'export'로 빌드한 별도의 out 디렉터리를 정적 산출물로 씁니다.

Amplify는 지원되는 버전과 기능 범위 안에서 Git 기반 배포와 AWS 백엔드 통합을 한곳에서 관리하기 쉽고, 간편한 CI/CD 파이프라인을 제공합니다. 대신 AWS 문서가 Edge API Routes, Edge middleware, 온디맨드 ISR, 스트리밍처럼 공식적으로 지원하지 않는다고 밝힌 기능이 있으며, 버전 호환성과 비용을 함께 관리해야 합니다.

AWS EC2 (Traditional Server Hosting)

EC2(Elastic Compute Cloud)는 가상 서버(인스턴스)를 만들어 Node.js 서버를 직접 실행하는 방식입니다. Node.js 서버의 설정과 배포를 직접 제어할 수 있지만, TLS, 프로세스, 캐시, 확장 같은 인프라 운영도 맡아야 합니다.

먼저 Ubuntu나 Amazon Linux 같은 운영 체제로 EC2 인스턴스를 만들고 SSH로 접속해, Node.js와 npm(또는 yarn)을 설치합니다. Git 저장소에서 Next.js 프로젝트를 받아 npm install과 npm run build를 실행한 뒤, npm start(또는 next start)로 프로덕션 서버를 실행합니다. pm2나 systemd 같은 도구로 애플리케이션이 백그라운드에서 계속 실행되도록 관리하고, Nginx나 Apache로 80번과 443번 포트의 요청을 Next.js 서버(기본 3000번 포트)로 프록시합니다. Let's Encrypt 같은 SSL 인증서도 직접 설정해야 합니다. 마지막으로 Jenkins, AWS CodePipeline, GitHub Actions 같은 CI/CD 도구로 코드를 푸시하면 자동으로 빌드하고 배포하는 파이프라인을 만듭니다.

EC2는 제어권이 넓고 인프라를 유연하게 구성할 수 있으며 복잡한 사용자 정의 설정도 가능하지만, 인프라를 설정하고 관리하는 부담이 크고 높은 운영 지식이 필요하며 비용 관리도 복잡합니다.

더 깊이: 서버를 여러 대로 늘릴 때 맞춰야 하는 것

Next.js의 직접 호스팅 안내는 인스턴스를 여러 대 운영할 때 맞춰야 할 값을 따로 정리합니다. 먼저 서버 액션의 암호화 키입니다. Next.js는 인라인 서버 액션이 캡처한 변수를 클라이언트로 보내기 전에 암호화하는데, 키는 기본적으로 빌드마다 새로 만들어집니다. 인스턴스마다 키가 다르면 한 인스턴스가 암호화한 값을 다른 인스턴스가 풀지 못해 "Failed to find Server Action" 오류가 나므로, NEXT_SERVER_ACTIONS_ENCRYPTION_KEY에 base64로 인코딩한 AES 키(16, 24, 32바이트 가운데 하나)를 넣어 모든 인스턴스가 같은 키를 쓰게 합니다. 환경마다 다시 빌드한다면 generateBuildId로 빌드 ID도 일정하게 맞춥니다.

둘째는 배포 중의 버전 차이(version skew)입니다. 새 버전을 차례로 배포하는 동안 브라우저가 이전 빌드의 JavaScript 파일이나 서버 액션 ID, 프리페치한 데이터를 들고 새 서버에 요청할 수 있습니다. next.config에 deploymentId를 정하면 정적 자원에 ?dpl= 쿼리가, 클라이언트 이동 요청에 x-deployment-id 헤더가 붙고, 서버는 자기 값과 다르면 클라이언트 이동 대신 문서 전체를 다시 불러옵니다. 이때 URL이나 로컬 저장소에 둔 상태는 남지만 useState 같은 컴포넌트 상태는 사라집니다.

셋째는 앞단의 프록시입니다. 공식 문서는 Next.js 서버를 인터넷에 바로 노출하지 말고, 잘못된 요청이나 느린 연결 공격, 요청 크기 제한, 요청 횟수 제한을 맡을 nginx 같은 리버스 프록시를 앞에 두라고 권합니다. 다만 nginx가 응답을 버퍼링하면 스트리밍이 동작하지 않으므로, X-Accel-Buffering: no 헤더로 버퍼링을 꺼야 loading.tsx의 대체 화면이 먼저 전달됩니다.

Heroku에 배포하기

Heroku는 애플리케이션 배포를 간단하게 해 주는 PaaS(Platform as a Service)로, Next.js 앱도 쉽게 배포할 수 있습니다. 먼저 Heroku CLI를 설치합니다. 운영 체제별 공식 설치 프로그램이나 macOS의 Homebrew처럼 자동으로 업데이트되는 공식 방법을 먼저 쓰며, npm install -g heroku는 손으로 업데이트해야 하는 대안입니다. 그다음 heroku create your-nextjs-app-name으로 Heroku 앱을 만듭니다.

package.json의 start 스크립트는 next start로 지정하고, Heroku가 제공하는 PORT 환경 변수를 시작 명령에서 씁니다.

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start -p $PORT"
  }
}

-p $PORT는 Heroku가 앱마다 정해 주는 포트 번호에서 요청을 기다리게 하는 부분입니다. Heroku의 web 프로세스는 이 포트에서 기다려야 외부 요청을 받을 수 있으므로, 포트를 코드나 스크립트에 고정해 두지 않습니다. Heroku는 Procfile에서 애플리케이션의 시작 명령을 찾으므로, 프로젝트 루트에 Procfile을 만듭니다. web: 뒤에 적은 명령이 HTTP 요청을 받을 프로세스의 시작 명령이며, 여기서는 위의 start 스크립트를 그대로 실행합니다.

# Procfile (프로젝트 루트에 생성)
web: npm run start

Procfile은 확장자 없이 정확히 이 이름이어야 하고, 저장소의 루트에 있어야 Heroku가 읽습니다. 그다음 Git 푸시로 배포합니다. 저장소 안에서 heroku create를 실행하면 heroku라는 원격 저장소가 추가되므로, 이 원격에 브랜치를 푸시하면 Heroku가 의존성 설치와 build 스크립트 실행을 마친 뒤 Procfile의 web 명령으로 앱을 시작합니다.

git add .
git commit -m "Initial Heroku deploy"
git push heroku main # 또는 master

환경 변수는 heroku config:set API_KEY=YOUR_API_KEY로 설정하거나 Heroku 대시보드에서 설정합니다.

Heroku는 배포가 매우 간편한 관리형 서비스입니다. 다만 예전의 상시 무료 dyno는 종료되었으므로, Eco나 Basic 같은 지금의 유료 실행 계획과 데이터 서비스 비용을 함께 계산해야 합니다. Vercel 전용 기능과 같은 이미지 최적화 구성을 자동으로 주지는 않으므로 운영 방식을 직접 정해야 합니다.

정적 웹사이트 호스팅 (SSG 전용)

Next.js의 output: 'export' 설정과 next build로 HTML, CSS, JavaScript 파일만 내보내 배포하는 경우입니다. 이때는 요청할 때의 SSR, 서버 액션, 동적 Route Handler처럼 서버 실행이 필요한 기능을 쓸 수 없으며, 빌드할 때 결과를 확정할 수 있는 GET Route Handler는 정적 파일로 내보낼 수 있습니다. 먼저 next.config.ts에 output: 'export' 옵션을 추가합니다.

import type { NextConfig } from 'next';

const nextConfig: NextConfig = {
  output: 'export', // 정적 HTML 파일로 내보내기
  trailingSlash: true, // /about/index.html 형태로 내보내기
  images: { unoptimized: true }, // 기본 이미지 최적화 서버를 사용하지 않음
};

export default nextConfig;

정적 내보내기에는 기본 next/image 최적화 서버가 없으므로, unoptimized: true를 켜거나 별도의 사용자 정의 이미지 로더를 설정해야 합니다. GitHub Pages의 사용자나 조직 루트 사이트(https://user.github.io)는 위 설정을 그대로 쓸 수 있습니다. 프로젝트 사이트(https://user.github.io/repository-name)라면 빌드할 때 basePath: '/repository-name'도 설정해야 Link, 라우터, _next 자산 경로가 저장소의 하위 경로를 가리킵니다. public/ 파일을 문자열 경로로 참조할 때도 같은 접두사를 직접 반영합니다.

npm run build를 실행하면 out 디렉터리에 정적 파일이 만들어지며, 이 파일을 여러 서비스에 올려 배포합니다. GitHub Pages는 .github/workflows에 워크플로를 설정해 out 디렉터리를 배포하고, Netlify는 publish 디렉터리를 out으로 설정합니다. AWS S3와 CloudFront를 쓴다면 S3 버킷에 파일을 올리고 CloudFront로 CDN 배포를 하며, /about에 직접 접근했을 때 /about/index.html로 연결되도록 CloudFront Function이나 오리진 재작성 규칙을 설정합니다.

정적 호스팅은 매우 빠르고 저렴하며 확장성이 높지만, 요청할 때의 SSR, 서버 액션, 동적 Route Handler, 기본 next/image 최적화 서버 같은 Next.js의 서버 실행 기능은 쓸 수 없습니다.

환경 변수 및 보안 고려사항

다른 호스팅 플랫폼에 배포할 때도 환경 변수 관리가 중요합니다. 호스팅 플랫폼마다 AWS Systems Manager Parameter Store, Heroku Config Vars, Netlify 환경 변수 설정처럼 환경 변수를 설정하는 고유한 방법이 있으므로, 그 플랫폼의 문서를 참조해 설정합니다.

빌드 시점과 런타임도 구분합니다. NEXT_PUBLIC_ 접두사가 붙은 값은 빌드할 때 클라이언트 번들에 들어가므로, 이후에 바꿔도 기존 빌드에는 반영되지 않습니다. 접두사가 없는 서버 전용 값은 동적으로 렌더링하는 서버 코드가 런타임에 읽을 수 있으므로, 플랫폼의 런타임 환경 변수 기능으로 관리합니다. 정적 내보내기에는 런타임 서버가 없다는 점도 구분합니다. 민감한 정보는 클라이언트 번들에 절대 노출되지 않도록 NEXT_PUBLIC_ 접두사에 주의하고, 각 플랫폼의 보안 지침을 따릅니다.

정리

• 호스팅은 관리형 어댑터, 직접 운영하는 Node.js 서버, 정적 내보내기로 나뉘며, 쓰는 Next.js 기능과 버전을 지원하는지가 먼저입니다.
• Netlify는 OpenNext 기반 어댑터로 Next.js를 자동 감지하므로, 기본 빌드 설정을 쓰고 모노레포처럼 필요한 경우에만 netlify.toml을 고칩니다.
• AWS Amplify의 관리형 SSR은 지원표에서 버전을 확인해야 하며, EC2나 Heroku처럼 서버를 직접 실행하면 프로세스와 TLS 같은 운영도 맡습니다.
• output: 'export'는 out 디렉터리에 정적 파일만 만들므로 서버 실행 기능을 쓸 수 없고, 이미지 최적화와 하위 경로를 따로 설정합니다.
• NEXT_PUBLIC_ 값은 빌드할 때 고정되고, 서버 전용 값은 플랫폼의 런타임 환경 변수로 관리합니다.

연습 문제

1. 요구 기능으로 호스팅 고르기

상품 목록이 빌드할 때 확정되고 로그인이나 서버 쓰기가 없는 사이트와, 요청 쿠키로 사용자마다 주문 목록을 보여 주고 서버 액션으로 주문을 저장하는 사이트를 각각 배포하려고 합니다. 두 사이트를 같은 out 디렉터리 업로드 방식으로 처리할 수 있을까요? Next.js 16으로 만든 두 번째 사이트를 Amplify Hosting compute로 바로 옮겨도 될까요?

2. 하위 경로 점검하기

프로젝트 사이트의 접두사가 /repository-name이고 파일이 public/logo.png라면, 문자열로 지정하는 이미지 주소는 무엇이어야 할까요? 같은 사이트에서 /about을 직접 열었을 때 404가 난다면, 빌드 성공만으로 어떤 설정까지 확인했다고 할 수 있을까요?

3. Heroku의 포트

Heroku에서 start 스크립트를 next start -p 3000으로 고정했더니 앱이 시작되지 않고 시간 초과 오류가 났습니다. 왜 그럴까요?

Next.js를 직접 호스팅하는 방법과 배포 방식별 지원 기능은 공식 문서의 Deploying 안내와 Self-Hosting 안내에서 확인할 수 있습니다.

이것으로 15장을 마칩니다. 15장에서는 Vercel 배포와 환경 변수 설정, 커스텀 도메인 연결, 그리고 다른 호스팅 플랫폼에 배포하는 방법과 각 방식의 지원 범위를 정리했습니다. 다음 장의 국제화 라우팅부터는 국제화, PWA, 서버리스 함수, WebSocket 같은 고급 기능을 알아봅니다.