Nuxt 3에서 Vercel 배포 시 발생한 md 파일 로딩 문제 해결기

내가 마주한 에러

로컬 환경에서 잘 동작하던 Nuxt 3 웹 어플리케이션이 Vercel 배포 환경에서 예상치 못한 에러를 발생시켰습니다.

이슈 재현 경로

메인 페이지(/)에서 이동 버튼을 통해 /blog 블로그 리스트 페이지로 이동.
블로그 리스트 페이지에서 md 파일들은 정상적으로 호출됨.
그러나 /blog 페이지에서 리로드를 수행하면 에러가 발생.

Vercel에서 받은 에러 로그

Failed to execute SQL INSERT INTO _content_blog VALUES ('blog/blog/nuxt3.md',  
'Nuxt3', '{"type":"minimal","value":[["h1",{"id":"hello-world"},"Hello World"], 
["p", {},"Welcome to my blog powered by Nuxt Content!"]], "toc":{"title":"", 
"searchDepth":2,"depth":2,"links":[]}}', 'How to start Nuxt', 'md', ' 
{"date":"2025-01-19"}', 'true', '/blog/nuxt3', '{"title":"Nuxt3","description":"How  
to start Nuxt"}', 'blog/nuxt3');: connect ECONNREFUSED 127.0.0.1:5432

에러 분석

connect ECONNREFUSED 127.0.0.1:5432
- 이 에러는 데이터베이스 연결이 거부되었음을 의미합니다.
- Nuxt Content 모듈이 배포 환경에서 데이터를 동적으로 처리하기 위해 로컬 데이터베이스 연결을 시도했으나, 정적 호스팅 환경(Vercel)에서는 데이터베이스 서버가 실행되지 않아 발생.
왜 리로드에서만 에러가 발생했을까?
- Vercel의 정적 사이트는 미리 생성된 HTML 파일을 제공합니다. 그러나 /blog 경로에서 리로드 시 서버가 존재하지 않으므로 동적으로 데이터를 가져오려는 요청이 실패했습니다.
- 정적으로 생성되지 않은 경로(/blog/:slug)는 배포 환경에서 지원되지 않았기 때문입니다.

해결 방법: prerender 설정 추가

Nuxt 3의 nitro.prerender 설정을 사용해 모든 블로그 경로를 정적으로 생성하도록 설정했습니다.
정적 경로로 렌더링함으로써 배포 환경에서도 데이터베이스 연결 없이 동작하도록 수정했습니다.

해결 코드 (nuxt.config.ts)

import { promises as fs } from 'fs';
import { resolve } from 'path';

export default defineNuxtConfig({
  nitro: {
    prerender: {
      // 정적으로 생성할 경로를 배열로 반환
      routes: await (async () => {
        // content/blog 디렉토리의 .md 파일 기준으로 경로 생성
        const blogFiles = await fs.readdir(resolve('content/blog'));
        const blogRoutes = blogFiles.map(file => `/blog/${file.replace('.md', '')}`);

        // 필요한 경로들을 반환
        return ['/blog', '/', ...blogRoutes];
      })(),
    },
  },
});

코드 설명 블로그 경로 생성: content/blog 디렉토리에 있는 모든 .md 파일의 이름을 기반으로 /blog/:slug 경로를 생성합니다.

정적 경로와 동적 경로 통합:

/blog: 블로그 리스트 페이지. /blog/:slug: 각 블로그 포스트 페이지. 배포 환경에 정적 파일 제공: 배포 시 .output/public 디렉토리에 HTML 파일들이 정적으로 생성되어 Vercel에서 문제가 발생하지 않음.

결과 확인 로컬 환경 npm run dev 실행 후: / 메인 페이지, /blog 블로그 리스트 페이지, /blog/:slug 포스트 페이지가 모두 정상 작동. 배포 환경 (Vercel) /blog로 이동 및 리로드 시 더 이상 에러가 발생하지 않음. /blog/:slug 경로의 정적 HTML 파일이 정적으로 제공되므로 빠르고 안정적인 성능 제공.