시작하기

Node.js, Next.js, Nuxt 애플리케이션.

Node.js 프로젝트를 감지하고 시작하는 방식: Node 버전, 패키지 매니저, Next.js와 Nuxt(서버 또는 정적), SvelteKit, Astro, Express 등, PORT 변수, Prisma 마이그레이션.

2 분 소요

package.json이 있는 저장소는 Node.js 프로젝트입니다. 프레임워크, 패키지 매니저, Node 버전을 자동으로 정해 빌드하고 시작하므로 푸시만 하면 됩니다.

Node 버전과 패키지 매니저

  • Node.js — package.json의 engines.node 또는 .nvmrc에서 가져오며, 24, 22, 20, 18, 16 중 조건에 맞는 가장 최신 버전을 사용합니다. 둘 다 없으면 Node.js 22입니다.
  • 패키지 매니저 — 잠금 파일로 결정합니다. pnpm-lock.yaml → pnpm, yarn.lock → yarn, 그 외에는 npm(package-lock.json이 있으면 npm ci)입니다.
  • 빌드 — package.json에 build 스크립트가 있으면 실행합니다.

프레임워크

프레임워크실행 방식
Next.js서버로 실행(next start) — 서버 렌더링, API 라우트, 미들웨어가 평소처럼 작동
output: 'export'를 사용한 Next.jsout의 정적 사이트로
Nuxt서버로 실행(.output/server/index.mjs)
ssr: false와 generate 스크립트를 사용한 Nuxt.output/public의 정적 사이트로
SvelteKitadapter-node이면 서버로, adapter-static이면 정적 사이트로
Astro정적 사이트로, @astrojs/node이면 서버로
NestJS빌드 후 dist/main.js
Express, Fastify, Koa, Hono 및 기타 서버scripts.start의 파일(node server.js), 없으면 main, 그다음 server.js, app.js, index.js 또는 main.js

Vite, Create React App, Angular, Vue CLI 등 프런트엔드 전용 프로젝트는 정적 사이트로 제공됩니다. 정적 사이트를 참고하세요.

PORT에서 수신

서버는 PORT 변수의 포트에서, 모든 인터페이스로 수신해야 합니다.

const port = process.env.PORT || 3000
app.listen(port, '0.0.0.0')

Next.js와 Nuxt는 이를 자동으로 처리합니다. 애플리케이션이 고정 포트에서 수신하면 방문자를 받을 수 없으며, 배포는 시작 확인 단계에서 멈추고 이전 버전이 계속 실행됩니다.

빌드 시점의 값

변수 탭의 변수는 실행 중인 애플리케이션에 전달되며 빌드에는 전달되지 않습니다. Next.js의 NEXT_PUBLIC_…나 VITE_…처럼 빌드가 클라이언트 코드에 넣는 값은 저장소에서 읽습니다. 예를 들어 커밋된 .env.production 파일입니다. 서버 측 코드는 평소처럼 변수 탭의 값을 읽습니다.

직접 지정하는 시작 명령

자동으로 감지된 시작 방식이 원하는 것과 다르면 설정 → 빌드 설정 → 시작 명령을 지정하세요. 예: node dist/server.js 또는 npm run start:prod. 설치 및 빌드 명령도 여기서 변경할 수 있습니다.

데이터베이스와 Prisma

프로젝트에 PostgreSQL 또는 MySQL을 추가하고 DATABASE_URL을 읽으세요. 이 변수는 자동으로 설정됩니다. 의존성에 Prisma가 있으면 권장 릴리스 명령은 npx prisma migrate deploy이며, 배포할 때마다 새 버전이 방문자를 받기 전에 실행됩니다. 배포를 참고하세요.

BullMQ 큐를 사용하려면 Valkey를 추가하고 REDIS_URL을 사용하세요. 큐 워커는 프로세스 탭이나 자체 리소스를 가진 별도 서비스에서 백그라운드 워커로 실행합니다. 프로젝트의 서비스를 참고하세요.

배포 후에도 남는 파일

배포할 때마다 저장소의 새 사본으로 시작합니다. 애플리케이션이 /data에 쓴 파일은 배포 사이에도 유지되고 매일 백업되지만, 다른 곳에 쓴 파일은 다음 배포 후 사라집니다. 업로드 파일과 미디어에는 보통 오브젝트 스토리지가 더 적합합니다.

모노레포

여러 프로젝트가 있는 저장소라면 애플리케이션을 만들 때 프로젝트 폴더(예: apps/web)를 지정하세요. 같은 저장소의 다른 폴더는 별도의 웹 서비스로 실행할 수 있습니다. 프로젝트의 서비스를 참고하세요.

아직 해결되지 않았나요?

채팅으로 문의하세요. 하루 중 언제든 AI 어시스턴트가 바로 답하고, 필요하면 엔지니어가 참여합니다.

지원팀에 문의