Next.js 안내서 · 6/6

배포

Next.js 애플리케이션은 Node.js 서버로 실행하거나, Docker 컨테이너로 묶거나, 정적 파일로 내보내거나, 각 플랫폼이 제공하는 통합 기능으로 배포할 수 있습니다. 어떤 방식을 고르느냐에 따라 쓸 수 있는 기능이 달라지므로, 먼저 운영용 빌드가 무엇을 만드는지 이해하는 것이 중요합니다.

운영용 빌드와 실행

next build는 코드를 최적화해 .next 폴더에 운영용 결과를 만들고, 정적으로 렌더링할 수 있는 페이지를 미리 생성합니다. 빌드가 끝나면 각 라우트가 정적으로 미리 만들어졌는지, 요청마다 서버에서 렌더링되는지 기호와 함께 목록으로 보여 주므로, 의도와 다르게 동적으로 바뀐 페이지가 없는지 확인합니다.

npm run build      # next build
npm run start      # next start, 기본 포트 3000

# 포트를 바꿔 실행
npx next start -p 8080

next start로 실행하는 Node.js 서버는 Server Component, Server Action, Route Handler, 이미지 최적화, 재검증 등 모든 기능을 지원합니다. 서버 한 대에 배포한다면 이 서버를 pm2나 systemd 같은 프로세스 관리자로 실행하고, 앞에 Nginx 같은 리버스 프록시를 두어 HTTPS와 압축을 맡기는 구성이 흔합니다.

standalone 출력

node_modules 전체를 서버에 올리지 않으려면 output: "standalone"을 설정합니다. 빌드할 때 실행에 꼭 필요한 파일만 추적해 .next/standalone 폴더에 모으고, next start 대신 쓸 수 있는 작은 server.js를 만들어 줍니다.

// next.config.ts
import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  output: "standalone",
};

export default nextConfig;

이 서버는 public과 .next/static 폴더를 자동으로 복사하지 않습니다. CDN에서 제공하지 않는다면 직접 복사한 뒤 실행합니다. 포트와 수신 주소는 PORT, HOSTNAME 환경 변수로 정합니다.

cp -r public .next/standalone/
cp -r .next/static .next/standalone/.next/
PORT=8080 HOSTNAME=0.0.0.0 node .next/standalone/server.js

Docker로 배포하기

standalone 출력은 작은 Docker 이미지를 만들 때 특히 유용합니다. 의존성 설치, 빌드, 실행 단계를 나눈 다단계 빌드로 최종 이미지에는 실행에 필요한 파일만 남깁니다.

FROM node:lts-alpine AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci

FROM node:lts-alpine AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN npm run build

FROM node:lts-alpine AS runner
WORKDIR /app
ENV NODE_ENV=production
ENV PORT=3000
ENV HOSTNAME=0.0.0.0
COPY --from=builder /app/public ./public
COPY --from=builder /app/.next/standalone ./
COPY --from=builder /app/.next/static ./.next/static
EXPOSE 3000
CMD ["node", "server.js"]

컨테이너를 여러 개 띄울 때는 캐시와 재검증 결과를 인스턴스끼리 공유해야 할 수 있습니다. 공식 자체 호스팅(self-hosting) 안내서의 캐시 핸들러 설정을 참고합니다.

정적 내보내기

서버 없이 HTML · CSS · 자바스크립트 파일만으로 운영하려면 output: "export"를 설정합니다. next build가 out 폴더에 정적 파일을 만들며, Nginx, Apache, 객체 저장소, GitHub Pages 같은 곳에 그대로 올릴 수 있습니다.

// next.config.ts
const nextConfig = {
  output: "export",
  trailingSlash: true,
};

export default nextConfig;

다만 요청 시점에 서버가 필요한 기능은 쓸 수 없습니다. 쿠키를 읽는 동적 렌더링, Server Action, 요청마다 응답을 만드는 Route Handler, 재검증, 기본 이미지 최적화 등이 제한되므로, 이런 기능이 필요하면 Node.js 서버나 플랫폼 배포를 고릅니다.

플랫폼에 배포하기

Next.js를 만든 Vercel은 별도 설정 없이 Git 저장소를 연결해 배포할 수 있습니다. 그 밖의 플랫폼은 Next.js의 배포 어댑터나 각 업체가 제공하는 통합 기능으로 지원하며, 지원 범위가 플랫폼마다 다르므로 각 업체의 Next.js 문서를 확인합니다.

환경 변수와 점검 목록

NEXT_PUBLIC_으로 시작하는 변수는 빌드할 때 브라우저 코드에 값이 박힙니다. 값을 바꾸면 다시 빌드해야 합니다.
서버 전용 변수는 실행 시점에 읽히므로 서버나 컨테이너 환경에서 주입합니다.
운영 전에 next build 결과의 정적 · 동적 표시, 이미지 최적화, 메타데이터, 오류 화면(error.tsx, not-found.tsx)을 점검합니다.
공식 문서의 운영 점검 목록(Production Checklist)으로 성능, 보안, 접근성을 한 번 더 확인합니다.

정리

next build로 빌드하고 next start로 실행하면 모든 기능을 쓸 수 있습니다.
output: "standalone"은 필요한 파일만 모아 Docker 이미지를 작게 만듭니다.
output: "export"는 정적 호스팅이 가능하지만 서버 기능을 쓸 수 없습니다.
플랫폼 배포는 지원 범위를 확인하고, NEXT_PUBLIC_ 변수는 빌드 시점에 고정된다는 점을 기억합니다.

공식 문서

이 장에 대해 질문이 있나요?