🚀 Brolog Vercel 배포를 시작하며

Brolog는 Nuxt 4 기반으로 제작한 개인 개발 블로그 프로젝트다.

처음 프로젝트를 만들 때부터 단순히 블로그 기능만 구현하는 것보다, 앞으로 진행할 프로젝트와 기술 학습 내용을 지속적으로 기록할 수 있는 개발 환경을 만드는 것을 목표로 했다.

현재 Brolog는 Nuxt Docus Theme 기반으로 구성되어 있으며, 공통 기능과 설정을 별도의 Nuxt Layer로 분리하는 Multi Layer 구조를 사용하고 있다.

로컬 개발 환경에서는 정상적으로 동작하고 있었지만, 실제 서비스를 제공하기 위해 Vercel 배포를 진행하면서 예상하지 못했던 몇 가지 문제를 만나게 되었다.

이번 글에서는 처음 Vercel 환경을 구성하면서 확인했던 과정을 기록한다.

📂 프로젝트 구조

현재 프로젝트는 다음과 같은 구조로 구성되어 있다.

Brolog

├── docs
│   ├── pages
│   ├── content
│   ├── app.vue
│   └── nuxt.config.ts
│
├── layer
│   ├── components
│   ├── composables
│   ├── middleware
│   └── nuxt.config.ts
│
└── package.json

docs는 실제 배포 대상이 되는 Nuxt 애플리케이션이며, layer는 공통 컴포넌트와 설정을 제공하는 확장 레이어 역할을 한다.

즉, 최종적으로 실행되는 Nuxt 애플리케이션은 docs 단독이 아니라, docs + layer가 결합된 형태이다.

🚨 1차 배포 시도와 Build Error 발생

Brolog 프로젝트를 Vercel에 배포하기 위해 먼저 GitHub 저장소를 연결하고 기본 배포 설정을 확인했다.

Vercel은 프로젝트 구조를 기준으로 일부 설정값을 자동으로 감지하고 있었고, 당시에는 별도의 설정 변경 없이 기본값으로 배포를 진행했다.

초기 설정은 다음과 같았다.

Root Directory : docs

Build Command는 Vercel에서 제공하는 기본 설정값을 그대로 사용했다.

npm run build or nuxt build

처음에는 로컬 환경에서 정상적으로 동작하고 있었기 때문에, 기본 빌드 명령어만으로도 배포가 가능할 것이라고 판단했다.

하지만 실제 Vercel 빌드 환경에서는 예상하지 못한 오류가 발생했고, 단순한 설정 문제가 아닌 Nuxt Multi Layer 구조와 빌드 과정 자체를 확인해야 했다.

처음에는 단순한 Vercel 설정 문제라고 생각했지만, 오류 메시지를 확인하면서 문제가 Nuxt Multi Layer 구조와 빌드 과정에 있다는 것을 알게 되었다.

발생한 오류는 다음과 같다.

Nuxt build error:

TSConfckParseError:
[vite:esbuild] parsing

/vercel/path0/layer/.nuxt/tsconfig.app.json

failed:

ENOENT: no such file or directory

오류 위치를 보면 실제 서비스 애플리케이션인 docs가 아니라 layer 디렉토리 내부의 .nuxt 파일을 찾고 있었다.

로컬 환경에서는 이미 개발 과정에서 Nuxt prepare 과정이 실행되면서 .nuxt 관련 파일들이 생성되어 있었지만,

Vercel은 새로운 빌드 컨테이너에서 시작하기 때문에 기존 생성 파일이 존재하지 않는다.

1. package.json의 build script 확인

오류 원인을 찾기 위해 프로젝트의 package.json을 다시 확인했다.

{
  "scripts": {
    "docs:build": "nuxt build docs --extends ../layer"
  }
}

기존 프로젝트 구조에서는 docs 애플리케이션을 빌드하면서 ../layer를 extends 하는 방식이었다.

그래서 Vercel Build Command를 다음과 같이 변경해보았다.

pnpm run docs:build

하지만 결과는 동일했다.

layer/.nuxt/tsconfig.app.json not found

처음에는 build 명령어가 문제라고 생각했지만, 실제 원인은 다른 곳에 있었다.

2. Root Directory를 비웠을 때 발생한 새로운 문제

다음으로 Vercel Root Directory를 기본값인 프로젝트 루트(./)로 변경했다.

그러자 빌드는 진행되었지만 예상하지 못한 결과가 나왔다.

배포된 페이지는 내가 제작한 Brolog 페이지가 아니라 Nuxt 기본 Welcome 페이지였다.

처음에는 빌드 성공처럼 보였지만, 실제로는 다른 Nuxt 프로젝트를 대상으로 빌드하고 있었다.

즉:

Root Directory: ./

↓

프로젝트 루트 기준 Nuxt 실행

↓

docs 애플리케이션이 아닌 기본 Nuxt 앱 빌드

가 발생한 것이다.

이 경험을 통해 Vercel의 Root Directory 설정은 단순히 파일 위치를 지정하는 옵션이 아니라, 실제 Nuxt 프로젝트의 기준점을 결정하는 중요한 설정이라는 것을 확인했다.

3. nuxi prepare 과정의 필요성 확인

여러 시도 끝에 이번 프로젝트 구조에서는

layer 역시 별도의 Nuxt 프로젝트 컨텍스트로 처리되기 때문에,

배포 과정에서 먼저 Layer의 Nuxt 준비 과정이 필요하다는 점을 확인했다.

최종적으로 성공한 Build Command는 다음이었다.

npx nuxi prepare ../layer && npx nuxi generate --extends ../layer

Vercel 설정은:

Root Directory

docs

로 유지했다.

동작 흐름은 다음과 같다.

Vercel Build 시작

↓

docs 기준 실행

↓

layer prepare 실행

↓

layer/.nuxt 생성

↓

docs + layer 병합

↓

Nuxt generate 실행

↓

정적 결과물 생성

기존 오류의 원인이었던:

layer/.nuxt/tsconfig.app.json not found

문제가 해결되었다.

4. build 방식도 시도해보았지만 발생한 문제

generate 이전에 다음 명령어도 테스트했다.

npx nuxi prepare ../layer && npx nuxi build --extends ../layer

하지만 결과는 다음과 같았다.

Error: Command exited with SIGKILL

Out of Memory event was detected during the build.

즉, build 과정 자체가 Vercel 빌드 컨테이너의 메모리 제한을 초과한 상황이었다.

처음에는 Vercel 환경에서 Node 메모리 제한을 조정하는 방식(NODE_OPTIONS=--max-old-space-size 등)으로 해결할 수 있을지 고민했다.

하지만 현재 Brolog 프로젝트의 목적은 별도의 서버 런타임이 필요한 애플리케이션 운영이 아니라, 개발 과정과 기술 기록을 제공하는 정적 콘텐츠 중심의 블로그 서비스였다.

따라서 서버 빌드 방식인 build를 유지하기보다 정적 생성 방식인 generate가 현재 배포 목적에 더 적합하다고 판단했고, 최종적으로 generate 방식을 선택하게 되었다.

다만 이 과정에서 build와 generate가 단순히 명령어 차이가 아니라 Nuxt 애플리케이션을 배포하는 방식 자체의 차이라는 점을 확인할 필요가 생겼다.

해당 내용은 다음 글에서 별도로 정리한다.

7. 이번 배포 과정에서 확인한 핵심 내용

이번 문제는 단순한 Vercel 설정 문제가 아니었다.

핵심 원인은 다음 세 가지였다.

Nuxt Multi Layer 구조

+

새로운 Vercel 빌드 환경

+

Layer 생성 컨텍스트 준비 과정 부재

로컬 환경에서는 이미 생성되어 있던 .nuxt 관련 파일들이 있었지만,

Vercel에서는 항상 초기 상태에서 프로젝트를 준비하기 때문에 Layer 역시 별도의 준비 과정이 필요했다.

최종 배포 흐름은 다음과 같이 정리할 수 있다.

docs Root Directory

↓

layer prepare

↓

Nuxt generate

↓

Vercel Static Deployment

이번 과정을 통해 Nuxt Layer 구조에서는 단순히 build 명령어만 실행하는 것이 아니라,

프로젝트 구조에 맞는 준비 과정과 배포 방식을 함께 고려해야 한다는 점을 확인했다.