Node.js, Next.js, Nuxt 애플리케이션.
Node.js 프로젝트를 감지하고 시작하는 방식: Node 버전, 패키지 매니저, Next.js와 Nuxt(서버 또는 정적), SvelteKit, Astro, Express 등, PORT 변수, Prisma 마이그레이션.
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.js | out의 정적 사이트로 |
| Nuxt | 서버로 실행(.output/server/index.mjs) |
ssr: false와 generate 스크립트를 사용한 Nuxt | .output/public의 정적 사이트로 |
| SvelteKit | adapter-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)를 지정하세요. 같은 저장소의 다른 폴더는 별도의 웹 서비스로 실행할 수 있습니다. 프로젝트의 서비스를 참고하세요.