[Brolog] Nuxt Multi Layer 프로젝트 Vercel 배포 (2) - Build Pipeline 오류 분석과 Nuxt 실행 구조 이해
🔍 Build Error를 이해하기 위한 Nuxt 실행 구조 분석
1편의 배포 과정에서 가장 처음 마주했던 문제는 다음 오류였다.
layer/.nuxt/tsconfig.app.json not found
처음에는 단순히 Vercel 설정 문제라고 생각했다.
하지만 문제를 해결하기 위해 과정을 따라가면서 확인해보니, 핵심 원인은 단순한 배포 설정이 아니라 Nuxt가 프로젝트를 준비하고 빌드하는 과정 자체에 대한 이해 부족이었다.
특히 이번 문제를 이해하기 위해서는 다음 개념들을 다시 확인할 필요가 있었다.
- Nuxt Multi Layer 구조
nuxi prepare가 생성하는 결과물- Nuxt
build과정 - Nuxt
generate과정 - SSR과 SSG의 차이
이번 글에서는 배포 과정에서 발생한 오류를 기준으로 Nuxt Build Pipeline이 실제로 어떻게 동작하는지 정리한다.
1. Nuxt Multi Layer 구조 이해
Brolog 프로젝트는 Nuxt Docus 기반으로 구성되어 있으며, Docus 내부 구조에서 사용하는 Nuxt Layer 구조를 그대로 활용하고 있다.
Docus는 문서 사이트 제작을 위한 테마 레이어를 제공하고,
실제 서비스 영역인 docs 프로젝트는 해당 Layer를 확장하는 형태로 동작한다.
이를 통해 기본 제공되는 컴포넌트, Layout, Middleware 등을 그대로 사용하면서, 필요한 경우 동일한 경로에 파일을 생성하여 프로젝트 단위로 Override할 수 있다.
Nuxt Content + Theme + Layer Architecture
Nuxt
├── Nuxt Content (Markdown/Data)
│
└── Docus (문서 사이트 프레임워크)
└── Nuxt Layer 사용
Nuxt에서는 다음과 같은 방식으로 Layer를 확장한다.
nuxt build docs --extends ../layer
여기서 중요한 점은 layer가 단순히 파일을 가져오는 폴더가 아니라는 것이다.
Nuxt는 빌드 과정에서 Layer 정보를 분석하고, 현재 애플리케이션과 병합하는 준비 과정이 필요하다.
2. .nuxt 디렉토리의 역할
Nuxt 프로젝트를 개발하다 보면 .nuxt라는 디렉토리가 생성된다.
Nuxt가 프로젝트 구조를 분석하고 자동 생성하는 빌드 준비 결과물이다.
대표적으로 포함되는 내용은 다음과 같다.
.nuxt
├── tsconfig.app.json
├── imports.d.ts
├── components.d.ts
├── nuxt.config.mjs
└── generated files
이 파일들은 다음 과정에서 활용된다.
소스 코드 분석
↓
Nuxt 내부 메타데이터 생성
↓
TypeScript 설정 생성
↓
Auto Import 정보 생성
↓
Vite 빌드 준비
로컬 환경에서는 개발 서버 실행 과정에서 이미 생성되어 있기 때문에 문제가 보이지 않았다.
하지만 Vercel은 항상 새로운 환경에서 프로젝트를 설치하기 때문에 기존 .nuxt 결과물이 존재하지 않는 상태에서 빌드가 시작된다.
3. nuxi prepare의 역할
이번 오류를 해결하는 핵심은 nuxi prepare였다.
npx nuxi prepare ../layer
이 명령어는 빌드 이전 단계에서 Nuxt 프로젝트를 분석하고 필요한 파일을 생성하는 준비 과정이다.
대략적인 흐름은 다음과 같다.
Nuxt Layer 분석
↓
Module 초기화
↓
Auto Import 분석
↓
Type 정의 생성
↓
.nuxt 디렉토리 생성
즉:
prepare 실행 전
layer/.nuxt 없음
prepare 실행 후
layer/.nuxt 생성
이 된다.
처음 발생했던 오류:
layer/.nuxt/tsconfig.app.json not found
는 결국 Layer에 대한 prepare 과정이 먼저 실행되지 않았기 때문에 발생한 문제였다.
4. Nuxt Build Pipeline 흐름
Nuxt Build의 전체 흐름은 다음과 같다.
Source Code
↓
nuxi prepare
↓
.nuxt 생성
↓
Vite Compile
↓
Vue 코드 변환
↓
Nitro Build
↓
Deployment Output 생성
각 단계별 역할은 다음과 같다.
① Prepare 단계
프로젝트 구조와 설정을 분석한다.
- Layer 병합
- Module 등록
- Auto Import 생성
- TypeScript 설정 생성
② Compile 단계
Vite를 통해 실제 애플리케이션 코드를 변환한다.
- Vue SFC 변환
- TypeScript 처리
- Bundle 생성
③ Nitro 단계
Nuxt의 서버 엔진인 Nitro가 배포 환경에 맞는 결과물을 생성한다.
SSR 방식에서는 이 단계에서 서버 실행 결과물이 만들어진다.
5. build와 generate의 차이
이번 배포 과정에서 가장 고민했던 부분은 build와 generate의 차이였다.
둘은 비슷해 보이지만 결과적으로 배포 방식이 다르다.
nuxt build
nuxi build
build는 서버 실행 환경을 포함한 애플리케이션을 생성한다.
흐름:
사용자 요청
↓
Nitro Server 실행
↓
페이지 생성
↓
HTML Response 반환
대표적으로 SSR(Server Side Rendering) 방식이다.
적합한 서비스:
- 로그인 기반 서비스
- 실시간 데이터 서비스
- 사용자별 페이지
결과물:
.output/
nuxt generate
nuxi generate
generate는 빌드 시점에 페이지를 미리 생성한다.
흐름:
Build Time
↓
페이지 생성
↓
HTML 파일 생성
↓
Static Hosting 배포
대표적으로 SSG(Static Site Generation) 방식이다.
적합한 서비스:
- 블로그
- 문서 사이트
- 기술 아카이브
Brolog 역시 개발 기록과 기술 문서를 제공하는 목적이기 때문에 정적 생성 방식이 적합했다.
6. CSR, SSR, SSG, ISR 차이
Nuxt에서 렌더링 방식을 이해하기 위해서는 CSR, SSR, SSG, ISR 차이를 이해해야 한다.
| 방식 | 생성 시점 | 특징 |
|---|---|---|
| CSR | 브라우저 실행 시 | SPA 구조, 초기 JS 로딩 필요 |
| SSR | 요청 시 서버 | 최신 데이터 제공 가능 |
| SSG | 빌드 시점 | 빠른 응답, 정적 콘텐츠 적합 |
| ISR | 일부 재생성 | SSG + 동적 갱신 |
📌 추가 정리
이번 배포 과정에서는
generate를 선택하면서 SSG 방식으로 배포하게 되었지만, Nuxt는 하나의 렌더링 방식만 지원하는 프레임워크가 아니다.CSR, SSR, SSG, ISR 각각의 차이와 Nuxt에서 이를 어떻게 선택하고 적용하는지는 별도의 글에서 정리한다.
Brolog 프로젝트 기준으로 보면:
기술 블로그
↓
Content 중심 / 변경 빈도 낮음
↓
SEO 중요
↓
정적 페이지 적합
↓
SSG(generate) 선택
이라는 판단이 가능했다.
7. 이번 오류를 통해 이해한 Nuxt 실행 구조
이번 문제는 단순히 Vercel 설정을 변경해서 해결한 문제가 아니었다.
실제 원인은 다음 구조였다.
Nuxt Multi Layer
+
Vercel 신규 빌드 환경
+
Layer prepare 과정 필요
로컬에서는 이미 생성되어 있던 .nuxt 파일이 있었기 때문에 문제가 드러나지 않았다.
하지만 CI/CD 환경에서는 항상 초기 상태에서 시작하기 때문에 Nuxt가 필요한 준비 과정을 명확하게 지정해야 한다.
최종 배포 흐름은 다음과 같다.
Vercel Build Start
↓
layer prepare
↓
docs + layer 병합
↓
Nuxt generate
↓
Static Deployment
이번 경험을 통해 Nuxt 프로젝트에서는 단순히 build 명령어를 실행하는 것이 아니라,
프로젝트 구조와 배포 방식에 맞는 Build Pipeline을 이해하는 것이 중요하다는 것을 확인했다.