🚀 Generate 배포 이후 발견한 Runtime 문제

이전 글에서는 Nuxt Multi Layer 구조로 구성된 Brolog 프로젝트를 Vercel에 배포하면서 발생한 layer/.nuxt 생성 오류를 분석하고,

nuxi prepare

과정과 build, generate 방식의 차이를 확인했다.

초기 배포 과정에서는 정적 콘텐츠 중심의 블로그라는 목적을 고려하여 generate 방식을 선택했다.

적용했던 Build Command는 다음과 같다.

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

결과적으로 정적 페이지 생성과 배포 자체는 정상적으로 완료되었다.

하지만 실제 서비스 환경에서 기능을 확인하는 과정에서 예상하지 못한 문제가 발견되었다.

Brolog은 단순한 Markdown 기반 문서 사이트가 아니라,

다음과 같은 Nuxt Runtime 기반 기능을 함께 사용하고 있었다.

Nuxt Content

+

Nuxt OG Image

+

AI Assistant

+

Nitro Runtime

generate 방식은 정적 결과물을 생성하는 데에는 적합하지만,

빌드 이후에도 서버 실행 환경이 필요한 기능까지 동일하게 제공하지는 않는다.

이번 글에서는 generate 배포 이후 확인한 Runtime 기능 문제와,

이를 해결하기 위해 Build 방식으로 변경한 과정,

그리고 Google AI Studio 전환 과정에서 발생한 SDK 버전 충돌 해결 과정을 기록한다.

1. Generate 배포 이후 확인한 문제

Nuxt OG Image 동작 확인

Brolog에서는 페이지 공유 시 사용할 Open Graph Image 생성을 위해 nuxt-og-image를 사용하고 있다.

하지만 generate 방식으로 배포한 이후 Vercel Production Deployment Overview에서 확인되는 Preview Image가 정상적으로 생성되지 않는 현상을 확인했다.

처음에는 단순한 SEO 메타데이터 설정 문제라고 생각했지만,

구조를 확인하면서 원인은 배포 방식 차이에 있었다.

Nuxt의 generate 방식은 빌드 시점에 페이지를 렌더링하여 정적 결과물을 생성한다.

Build Time

↓

HTML / Asset 생성

↓

Static Hosting

구조로 동작한다.

반면 Nuxt OG Image는 단순히 이미지 파일을 미리 생성하는 기능이 아니라,

요청 시점에 Nitro Runtime에서 이미지를 생성하는 방식으로 동작한다.

Request

↓

Nitro Server Route

↓

OG Image 생성

↓

Response

과정이 필요하다.

따라서 완전한 Static Output 환경에서는 Nitro Runtime 기반 기능들이 기대한 방식으로 동작하지 않을 수 있다는 점을 확인했다.

AI Assistant 동작 문제

또 다른 문제는 Docus에서 제공하는 AI Assistant 기능이었다.

generate 방식으로 배포한 이후 AI Assistant를 실행했을 때 정상적인 답변 UI가 표시되지 않았다.

대신 화면을 덮는 형태의 비정상적인 팝업이 나타났고,

내부에는 HTML 코드 형태의 응답 내용이 그대로 노출되는 현상이 발생했다.

처음에는 AI Provider 설정 문제라고 판단했지만,

응답 흐름을 확인하면서 다른 원인을 확인했다.

AI Assistant 요청은 단순히 브라우저에서 외부 API를 직접 호출하는 구조가 아니라,

Nuxt Server Runtime을 통해 API 요청과 Response Stream 처리가 이루어진다.

하지만 Static Generate 환경에서는 이러한 Runtime Layer가 정상적으로 유지되지 않았고,

클라이언트는 AI SDK가 기대하는 Response Format이 아닌 HTML Error Response를 전달받고 있었다.

이를 통해 문제의 핵심은 단순 API Key 설정이 아니라,

배포 방식과 Runtime 요구사항의 불일치라는 점을 확인했다.

2. Generate에서 Build 방식으로 변경

문제를 확인한 이후 현재 Brolog 프로젝트에서 필요한 실행 환경을 다시 판단했다.

처음에는 개발 블로그라는 목적 때문에 정적 생성 방식이 적합하다고 생각했다.

하지만 실제 사용하는 기능을 기준으로 보면:

Nuxt Content

+

OG Image Generator

+

AI Assistant

+

Server Runtime 기능

을 포함하고 있었다.

Nuxt 3/4의 서버 실행 환경은 Nitro Runtime 기반으로 구성된다.

SSR 렌더링,

API Route,

Server Middleware,

Runtime Config,

OG Image Generator와 같은 기능들은 Nitro Runtime 위에서 실행된다.

따라서 이러한 기능을 사용하는 프로젝트에서는 단순히 정적 파일 생성 여부보다,

Runtime Layer가 필요한지 판단하는 것이 중요하다.

이번 프로젝트에서는 Static Output보다 Nitro Runtime이 포함되는 Build 방식이 더 적합하다고 판단했다.

3. Build 방식 전환과 메모리 제한 해결

이전 글에서 확인했던 것처럼 일반적인 Nuxt Build 과정은 Vercel 환경에서 메모리 부족 문제가 발생했다.

기본 Build Command:

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

실행 결과:

Error: Command exited with SIGKILL

Out of Memory event was detected during the build.

Vercel Build Container 환경은 제한된 리소스에서 실행되기 때문에,

Nuxt Build 과정에서 생성되는 번들링 과정과 Nitro Server Bundle 생성 과정이 메모리 제한에 도달한 것으로 판단했다.

Brolog에서 사용하는 기능 특성상 Nitro Runtime이 필요한 기능들이 존재했고,

결국 Node 메모리 제한을 조정하는 방향으로 다시 시도했다.

최종 Build Command는 다음과 같다.

export NODE_OPTIONS="--max-old-space-size=6144" && npx nuxi prepare ../layer && pnpm run build --extends ../layer

결과적으로 Vercel 환경에서 Build가 정상적으로 완료되었다.

4. Build 전환 이후 확인한 변화

Nuxt OG Image 정상 동작

Build 방식으로 전환한 이후 Vercel Production Deployment Overview에서 Preview Image가 정상적으로 생성되는 것을 확인했다.

기존 generate 방식에서는 확인되지 않았던 Brolog 메인 화면 기반 이미지가 정상적으로 표시되었다.

이 과정에서 확인한 핵심은 다음과 같다.

generate

↓

Static Output 생성

↓

정적 파일 제공


build

↓

Nitro Server Bundle 생성

↓

Runtime 요청 처리 가능

Nuxt에서 사용하는 일부 기능은 단순히 페이지를 생성하는 것에서 끝나는 것이 아니라,

배포 이후 요청을 처리할 Runtime 환경을 필요로 한다.

이번 문제는 기능 자체의 오류라기보다,

프로젝트가 요구하는 Runtime 환경과 배포 방식의 차이에서 발생한 문제였다.

AI Assistant 오류 형태 변경

Build 전환 이후 기존처럼 화면 전체를 덮는 HTML 팝업 형태의 문제는 사라졌다.

하지만 AI Assistant 요청은 여전히 정상적인 답변을 반환하지 않았다.

확인 결과 HTTP Status 자체는:

200 OK

였지만,

Response Body 내부에는 오류 내용이 포함되어 있었다.

즉:

HTTP Layer

↓

정상 응답

↓

AI Provider 요청 과정에서 Error 발생

구조였다.

네트워크 요청 자체는 성공했지만,

AI Model Provider 연결 과정에서 문제가 발생하고 있었다.

5. Vercel AI Gateway 문제 확인

로그를 확인하면서 AI 오류 원인을 추적했다.

기존 AI Assistant 구조는 다음과 같았다.

Brolog AI Assistant

↓

Vercel AI Gateway

↓

AI Model Provider

문제는 Vercel AI Gateway 사용 조건이었다.

Vercel AI Gateway를 사용하기 위해서는 결제 수단 등록이 필요했다.

무료 사용 범위가 존재하더라도,

개인 프로젝트 환경에서는 예상하지 못한 과금 가능성을 관리하는 것이 중요하다고 판단했다.

따라서 AI Provider를 직접 관리하는 방식으로 변경하기로 했다.

최종적으로 Google AI Studio API를 사용하는 방향으로 변경했다.

6. Google AI Studio Provider 변경

변경 이후 구조는 다음과 같다.

Brolog AI Assistant

↓

AI SDK

↓

Google AI Studio API

↓

Gemini Model

Google AI Studio에서는 무료 사용 가능한 모델을 제공하고 있었고,

개인 개발 블로그 환경에서는 충분히 활용 가능한 수준이라고 판단했다.

또한 제공되는 모델은 변경될 수 있기 때문에,

모델명을 코드 내부에 직접 작성하지 않고 환경 변수로 분리했다.

예:

GOOGLE_AI_MODEL=gemini-model-name

이렇게 구성하면 모델 변경이 필요할 때 코드 수정 없이 환경 변수만 변경하면 된다.

7. AI SDK Provider 버전 충돌 해결

Google Provider 적용 과정에서 새로운 문제가 발생했다.

Google AI Studio 연동을 위해 다음 패키지를 설치했다.

pnpm add @ai-sdk/google

하지만 설치된 버전은 4.x 버전이었다.

기존 프로젝트에서는:

ai@6

버전을 사용하고 있었다.

확인 결과 내부 의존성 구조에서 차이가 있었다.

ai@6

└── @ai-sdk/provider@3


@ai-sdk/google@4

└── @ai-sdk/provider@4

같은 AI SDK 생태계 패키지였지만,

Major Version 차이로 인해 내부 Provider Interface가 호환되지 않았다.

결과적으로 Google Provider 버전을 프로젝트의 AI SDK 버전에 맞춰 변경했다.

pnpm add @ai-sdk/google@3

이후 Provider Dependency 충돌이 해결되었고,

Google AI Studio 기반 AI Assistant가 정상적으로 동작했다.

8. 현재 Brolog 배포 구조

현재 최종 배포 구조는 다음과 같다.

Vercel Build

↓

nuxi prepare ../layer

↓

Nuxt Build

↓

Nitro Runtime Deployment

↓

Google AI Studio API

AI Model 설정은:

Environment Variable

↓

Model 선택

↓

AI SDK Provider 연결

구조로 관리하고 있다.

마무리

이번 배포 과정에서는 단순히 빌드 성공 여부보다,

프로젝트에서 사용하는 기능이 어떤 실행 환경을 요구하는지 확인하는 과정이 중요했다.

처음에는 블로그 서비스라는 목적 때문에 generate 방식이 적합하다고 판단했지만,

실제 사용하고 있는 기능이 Nitro Runtime 기반 기능을 포함하고 있었기 때문에 Build 방식이 더 적합했다.

또한 AI 기능 적용 과정에서는 단순히 API Provider만 변경하는 것이 아니라,

AI SDK 생태계 내부 Dependency와 Provider Version 호환성까지 함께 확인해야 했다.

최종적으로 Brolog은:

Nuxt Multi Layer

+

Nuxt Build

+

Nitro Runtime

+

Google AI Studio

+

Environment Variable 기반 Model 관리

구조로 운영하게 되었다.

이번 과정은 단순한 배포 설정 변경이 아니라,

Nuxt 애플리케이션이 정적 생성과 Runtime 실행 환경 사이에서 어떻게 동작하는지 확인할 수 있었던 과정이었다.