Next.js

Next.js는 나이트로쉽이 직접 지원하는(관리형) 프레임워크입니다. 별도 어댑터 설정 없이 정적 페이지, 프리렌더·ISR, 서버 라우트, API 라우트, 미들웨어, 이미지 최적화가 모두 동작합니다. output: 'standalone'도 필요 없습니다.

준비물제목 링크 복사

• Next.js 16.2 이상. 배포 루트의 package.json에 next가 있어야 하며, 원격 빌더가 의존성을 설치한 뒤 실제 설치된 버전을 확인합니다.
• 컴퓨트 리전. 서버가 실행될 지역입니다. 기본값이 없으니 아래 설정에서 꼭 하나 고르세요.

배포하기제목 링크 복사

curl -fsSL https://nitroship.co/install.sh | bash
ntro login

ntro apps create my-next-app
ntro deploy . --prod

원격 빌더가 의존성 설치와 next build를 대신 하고, 정적 파일·서버 코드를 나눠 배포합니다. 내 컴퓨터에서 빌드해서 올리고 싶다면 의존성을 먼저 설치한 뒤 --local을 붙이세요.

ntro deploy . --prod --local

배포가 끝나면 CLI가 보여 준 주소에서 정적 페이지와 서버 라우트를 열어 보세요. SSG·SSR·ISR·API 라우트를 모두 담은 예제는 저장소의 examples/hello-next에 있습니다.

설정제목 링크 복사

서버 리전·사양은 두 곳 중 편한 곳에서 정합니다.

• 콘솔의 App Settings > Compute
• 배포 루트의 nitroship.json

{
  "compute": {
    "regions": ["kr-icn"],
    "tier": "standard"
  }
}

둘 다 적혀 있으면 항목별로 nitroship.json이 이깁니다. 예를 들어 파일에 regions만 있다면 리전은 파일 값, 티어는 콘솔 값을 씁니다. 전체 항목과 기본값은 CLI 설정 > 컴퓨트 설정에 있습니다.

빌드 명령을 바꾸려면 build.command를 쓰세요. build.outputDirectory는 Next.js에서는 무시됩니다.

공개 SSR 응답 캐시제목 링크 복사

공개 동적 경로에는 Next.js가 생성하는 Cache-Control에 의존하지 않고 next.config의 headers() 또는 middleware로 CDN-Cache-Control을 설정합니다. 선택적 Edge 응답 캐시는 프리렌더/ISR과 별개이며 운영자가 활성화해야 합니다. 개인화 응답은 캐시하지 않습니다. Set-Cookie, 선택한 정책의 private, Vary: Cookie는 저장을 막습니다. 헤더 우선순위·한도·태그·invalidate/delete 차이는 캐시 무효화를 참고합니다. 저장소의 examples/hello-ssr-cache는 렌더 시각과 호스트별 캐시 응답을 보여줍니다.

Next.js가 minimal mode로 실행되어도 Edge는 평가된 설정 헤더를 Compute에 전달합니다. 함수의 정책 헤더는 같은 이름의 설정값을 대체하지만 Vary와 캐시 태그는 합집합으로 적용합니다. 따라서 Next.js가 Vary 필드를 추가해도 설정의 Vary: Cookie는 캐시를 막습니다. 태그 128개 제한은 합집합에 적용합니다. 선택된 설정 헤더의 인코딩된 전달값은 최대 8 KiB이며 초과하면 로그를 남기고 설정을 무시하므로 과대한 설정에 캐시 정책을 의존하지 마세요.

알아둘 점제목 링크 복사

• 이미지: Next.js 기본 이미지 로더 설정은 자동으로 반영됩니다. 이미지 옵션은 next.config에서만 조정하고, nitroship.json에 images를 따로 적지 마세요.
• 다국어 도메인: i18n.domains(언어별 도메인)는 지원하지 않습니다. /ko, /en 같은 언어 경로를 사용하세요.

고급: 준비 상태 확인과 워밍업제목 링크 복사

평소에는 몰라도 되는 내용입니다. 앱이 처음 뜰 때 하는 일이 있거나, 콜드 스타트를 조정하고 싶을 때 읽어 보세요.

배경: 시드 스냅샷제목 링크 복사

나이트로쉽은 요청이 몰릴 때 새 인스턴스를 빨리 띄우기 위해, 앱을 한 번 완전히 띄운 상태를 스냅샷(시드) 으로 저장해 두고 이를 복원해서 씁니다. 첫 화면을 미리 한 번 그려 두는 것이 워밍업입니다.

헬스 체크는 "앱이 요청을 받을 준비가 됐는지"를 확인하는 단계로, 새로 시작할 때(콜드 스타트), 시드를 만들 때, 일시 정지했던 인스턴스(체크포인트)를 되살릴 때, 복원에 실패해 새로 시작할 때 실행됩니다. 이미 만들어 둔 시드를 복원할 때는 포트가 연결을 받는지만 빠르게 확인합니다.

헬스 체크: /__nitroship/health제목 링크 복사

새로 빌드한 Next.js 앱에는 나이트로쉽이 /__nitroship/health 경로를 자동으로 추가하고, 이 경로를 헬스 체크에 씁니다. 따로 설정할 것은 없습니다.

• Next.js 서버 준비(NextServer.prepare())와 라우트 미리 불러오기가 끝나기 전에는 503, 끝나면 200을 돌려줍니다. 본문은 비어 있습니다.
• 미리 불러오기는 각 라우트 파일을 import만 할 뿐, 페이지 렌더링·라우트 핸들러·미들웨어는 실행하지 않습니다.

미리 불러오기 끄기: 비교·문제 해결용으로 끄고 싶다면 환경 변수 NITROSHIP_NEXT_PRELOAD=0을 설정하고 다시 배포하세요. 그러면 헬스 체크는 prepare()만 기다립니다. 값이 1이거나 없으면 켜진 상태입니다.

내 엔드포인트로 바꾸기: 직접 만든 경로로 확인하려면 nitroship.json에 지정합니다. 이 경로는 앱에서 직접 구현해야 하며, /__nitroship/health는 바꾼 뒤에도 예약된 채로 남습니다.

{"compute": {"healthPath": "/api/healthz"}}

어느 경로든 헬스 체크는 그 경로로 GET 요청을 보내 확인합니다.

• 2xx, 3xx, 404 응답이면 준비된 것으로 봅니다.
• 요청 한 번에 응답 헤더를 최대 2초 기다리고, 될 때까지 다시 시도합니다. 전체 제한 시간은 30초입니다.

워밍업 요청: GET /제목 링크 복사

시드 스냅샷을 만들 때 헬스 체크를 통과하면, 나이트로쉽이 앱에 GET / 요청을 한 번 보냅니다. 첫 화면을 그리는 코드를 미리 실행해 두기 위해서이며, 응답을 끝까지 받은 뒤 스냅샷을 찍습니다.

• 요청에는 User-Agent: nitroship-seed-warmup, x-nitroship-warmup: 1 헤더가 붙습니다.
• 헬스 체크와 달리 실제로 페이지를 렌더링하고 미들웨어도 실행합니다. 방문 통계 기록처럼 부수 효과가 있는 코드라면 위 헤더로 이 요청을 걸러 내세요.
• 정해진 시간 안에 최선 노력으로 보내므로, 오류나 시간 초과가 나도 배포는 실패하지 않습니다.
• 스냅샷 복원 때나 실제 사용자 요청마다 보내는 요청은 아닙니다. compute.healthPath를 바꿔도 워밍업 경로는 / 그대로입니다.

기존 배포에는 적용되지 않습니다제목 링크 복사

헬스 체크 경로와 워밍업은 빌드할 때 배포에 기록됩니다. 이 기능이 생기기 전에 만든 배포는 원래 헬스 경로(보통 /)를 계속 쓰고 워밍업도 하지 않습니다. 재배포, 지금 적용, 승격, 롤백은 기록된 값을 그대로 유지하므로, 새 동작을 쓰려면 다시 빌드해야 합니다. Next.js가 아닌 앱에는 워밍업 요청을 보내지 않습니다.

관련 가이드제목 링크 복사

이미지 최적화 · 캐시 무효화 · 환경 변수 · Vercel에서 이전