Vercel에서 이전
Vercel 프로젝트를 나이트로쉽으로 옮길 때 바꿔야 할 것과 그대로 쓸 수 있는 것을 정리했습니다.
프로젝트 소스와 주소 규칙을 나이트로쉽으로 옮긴 뒤, 맞는 관리형 프리셋으로 빌드하세요. 명령 이름이 거의 같고, 지원하는 vercel.json의 주소 규칙도 그대로 읽습니다. 아래 순서대로 확인하세요.
1. 배포 방식을 고릅니다
관리형 프리셋은 소스를 나이트로쉽용으로 빌드하며, 임의의 Vercel 함수나 미리 빌드된 Vercel 런타임 출력을 변환하지 않습니다. Vercel 전용 어댑터를 각 프레임워크 안내에서 요구하는 어댑터로 바꾸고, 프로젝트에 맞는 방식을 고르세요.
| 프로젝트 | 관리형 배포 방식 |
|---|---|
| Next.js | 전용 어댑터를 사용하는 관리형 Next.js |
| Nuxt | Nuxt: 관리형 Node 서버 또는 정적 생성 |
| Astro | Astro: 정적 출력 또는 standalone Node 서버 |
| SvelteKit | SvelteKit: adapter-node 서버 또는 adapter-static 사이트 |
| SolidStart, Analog, TanStack Start | 관리형 Node 빌드: SolidStart, Analog, TanStack Start |
| React Router, Remix | React Router: 관리형 Node SSR 또는 정적 SPA 모드. Remix: 관리형 Node 서버 |
| Angular, Qwik | Angular: 정적 출력 또는 관리형 Node SSR. Qwik: 정적 또는 Node 어댑터 |
| NestJS, Express, Fastify, Hono, Koa | 관리형 Node 서버 |
| Gatsby, Docusaurus, VitePress, Eleventy | 정적 사이트 생성기: Node 도구를 사용하는 관리형 정적 빌드 |
| Hugo, Jekyll, MkDocs | 정적 사이트 생성기: 정적 파일만 추출하는 도구 컨테이너 |
| Vite, Create React App | Vite·React SPA: 관리형 정적 빌드 |
| 일반 HTML 또는 일반 정적 빌드 | 정적 HTML과 정적 사이트 안내 |
| Laravel, Symfony, WordPress, PHP | 생성된 서버 컨테이너: Laravel, Symfony, WordPress, PHP |
| Django, FastAPI, Flask | 생성된 서버 컨테이너: Django, Python 서버 |
| Rails, Phoenix | 생성된 서버 컨테이너: Rails, Phoenix |
| Go, Rust, Spring Boot, .NET | 생성된 서버 컨테이너: Go, Rust, Spring Boot, .NET |
| 프리셋으로 다루지 않는 사용자 지정 서버·빌드 | 직접 작성한 Dockerfile |
관리형 출력은 네 종류입니다.
static: 서버 없이 CDN에 파일만 게시합니다.node-server: 관리형 Node 번들과 CDN에서 서빙하는 클라이언트 에셋입니다.container: 비루트 사용자로 실행하는 서버용 OCI 이미지를 생성합니다. 공개 에셋은/nitroship/static에 복사해 CDN에서 서빙합니다.container-static: 도구 이미지에서 정적 사이트만 추출하며 컴퓨트 런타임은 없습니다.
관리형 서버는 0.0.0.0:$PORT에서 수신하며 기본 포트는 3000입니다. Node 서버 프리셋에는 진입 파일·start 스크립트·main 중 하나로 지정한 실제 Node 진입점이 필요합니다. TypeScript 프로젝트에는 실행 가능한 JavaScript를 출력하는 빌드 스크립트가 필요합니다. 데이터베이스 마이그레이션·큐 워커·스케줄러는 자동 실행하지 않습니다.
nitroship.json의 build.framework는 루트 Dockerfile이 있어도 프레임워크를 명시적으로 선택하며, build.dockerfile과 함께 설정하면 오류가 납니다. 명시하지 않으면 지정한 Dockerfile 또는 루트의 Dockerfile.nitroship/Dockerfile → 전용 Next.js 어댑터 → 관리형 프레임워크 프리셋 → 일반 정적 파일 순으로 감지합니다. --local은 정적 빌드와 관리형 Node 빌드를 지원합니다. container·container-static 프리셋은 원격 빌더가 필요하므로 --local을 빼세요.
2. vercel.json을 확인합니다
ntro는 배포 루트의 vercel.json에서 다음 항목만 읽어 그대로 적용합니다.
cleanUrls, trailingSlash, redirects, rewrites, headers, routes, crons, version
그 밖의 항목이 있으면 배포가 거부됩니다
buildCommand, outputDirectory, framework, functions, regions, images 같은 Vercel 전용 항목은 지원하지 않으며, 들어 있으면 오류가 납니다. 이런 설정은 vercel.json에서 빼고, 필요하면 아래처럼 nitroship.json으로 옮기세요.
| Vercel에서 하던 설정 | Nitroship에서는 |
|---|---|
| 빌드 명령·출력 폴더 | nitroship.json의 build.command, build.outputDirectory |
| 프레임워크 프리셋 | 나이트로쉽 프레임워크 슬러그를 사용하는 nitroship.json의 build.framework |
| 함수 리전·사양 | nitroship.json의 compute, 또는 콘솔 App Settings > Compute |
| 이미지 최적화 | Next.js는 next.config, 그 외는 nitroship.json의 images (이미지 최적화) |
nitroship.json은 vercel.json의 모든 항목에 더해 build·compute·images까지 쓸 수 있는 상위 호환 파일입니다. 두 파일이 다 있으면 nitroship.json만 읽습니다. 옮기는 김에 vercel.json을 nitroship.json으로 이름을 바꾸는 것도 좋습니다.
3. 달라지는 점을 알아 둡니다
- Project → App. Vercel의 프로젝트가 나이트로쉽의 앱입니다. 팀은 그대로 팀입니다.
- 환경 변수 대상은
production과preview두 가지뿐입니다.development대상은 없습니다. 로컬 개발에는ntro env pull로 프리뷰 값을 받아 쓰세요. 자세한 내용은 환경 변수 문서를 참고하세요. - CLI 배포의 기본값이 다릅니다. 첫 배포만 프로덕션이고 그 뒤로는 프리뷰가 기본입니다. 계속 프로덕션에 바로 배포하려면 매번
--prod를 붙이세요. 자세한 내용은 배포 관리 문서를 참고하세요.
4. 명령 대응표
| Vercel CLI | Nitroship CLI |
|---|---|
vercel [path], vercel deploy [path] | ntro [path], ntro deploy [path] |
vercel --prod | ntro --prod |
vercel ls | ntro ls 또는 ntro deployments list |
vercel inspect <deployment> --logs | ntro inspect <deployment> --logs |
vercel logs <deployment> | ntro logs <deployment> |
vercel switch [team] | ntro switch [team] |
vercel project ls | ntro apps list |
vercel env pull [file] | ntro env pull [file] |
vercel upgrade | ntro upgrade 또는 ntro update |
team은 teams의 별칭이며, 명령 그룹 대부분에서 ls, rm, remove 같은 짧은 이름도 쓸 수 있습니다. 전체 목록은 명령 레퍼런스에 있습니다.
5. 배포 후 확인합니다
동작이 Vercel과 완전히 같다고 가정하지 말고, 배포한 뒤 주요 주소·리디렉트·API를 직접 열어 확인하세요.