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

Nuxt 3 웹 어플리케이션에서 Vercel 배포 환경에서 발생한 md 파일 로딩 문제를 분석하고 해결한 방법에 대해 공유합니다.

업데이트 (2026.10.16): 이 글의 해결 방법은 따라 하지 마세요. 아래에서 소개하는 "파일명으로 글 주소 목록을 만드는 코드"는 나중에 이 블로그의 사이트맵에 중복·깨진 주소를 만들어 구글 색인에 피해를 줬고, 지금은 지웠습니다. 에러의 진짜 원인은 Nuxt Content 버전이었습니다. 글 맨 아래 **"지금 돌아보면"**에 바른 해결 방법을 정리했습니다.

내가 마주한 에러

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

이슈 재현 경로

  1. 메인 페이지(/)에서 이동 버튼을 통해 /blog 블로그 리스트 페이지로 이동.
  2. 블로그 리스트 페이지에서 md 파일들은 정상적으로 호출됨.
  3. 그러나 /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

에러 분석

  1. connect ECONNREFUSED 127.0.0.1:5432
    • 이 에러는 데이터베이스 연결이 거부되었음을 의미합니다.
    • Nuxt Content 모듈이 배포 환경에서 데이터를 동적으로 처리하기 위해 로컬 데이터베이스 연결을 시도했으나, 정적 호스팅 환경(Vercel)에서는 데이터베이스 서버가 실행되지 않아 발생.
  2. 왜 리로드에서만 에러가 발생했을까?
    • 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 파일이 정적으로 제공되므로 빠르고 안정적인 성능 제공.


지금 돌아보면 (2026.10.16 업데이트)

이 해결 방법은 에러를 고친 게 아니라 가린 것이었다. 글 페이지를 빌드할 때 미리 HTML로 만들어 두니, 배포 환경에서 콘텐츠 DB를 읽을 일이 없어서 에러가 안 보였을 뿐이다.

이 글의 판단실제로는
Vercel은 정적 호스팅이라 서버가 없다이 블로그는 Vercel에서 서버 함수로 실행된다. 미리 만들지 않은 페이지는 요청 때 서버가 만든다
데이터베이스가 없어서 생긴 에러5432는 PostgreSQL 기본 포트다. 당시 Nuxt Content 버전이 Vercel 환경에서 콘텐츠 DB를 제대로 다루지 못한 것으로 보인다
파일명으로 글 주소 목록을 만들면 된다Nuxt Content는 파일명을 소문자·하이픈으로 바꿔 주소를 만든다. 파일명에 대문자나 공백이 있으면 이 코드가 만든 주소와 실제 주소가 달라진다

실제로 일어난 일

  1. 2026년 9월, 이 코드가 만든 주소(/blog/nuxt-useAsyncData-cache-error 같은 대문자 주소)가 사이트맵에 중복으로 올라가 있는 걸 발견하고 코드를 지웠다 (애드센스 ads.txt 경고를 받고 파헤치다가 찾은 진짜 색인 버그).
  2. 그러자 글 페이지가 다시 요청 때 서버에서 만들어지면서, 이 글과 비슷한 문제가 다시 나타났다. 이번에는 에러 없이 글 목록이 빈 배열로 나왔다. 둘 다 Vercel에서 콘텐츠 DB를 제대로 읽지 못한 문제였다.
  3. 원인은 @nuxt/content가 3.0.0에 고정돼 있던 것이었다. 3.16.1로 올리자 해결됐다 (배포만 하면 블로그 글이 하나도 안 보이던 버그).

지금 이 블로그의 설정

// nuxt.config.ts
nitro: {
  prerender: {
    crawlLinks: true,                                // 링크를 따라가며 페이지를 미리 만든다
    ignore: [(route: string) => route.includes("?")],
    routes: ["/en"],                                 // 링크로 닿지 않는 시작점만 직접 추가
  },
},
  • 글 주소 목록을 직접 만들지 않는다. Nuxt Content가 만든 주소를 그대로 믿는다.
  • 대신 모든 글을 링크로 나열한 전체 글 페이지(/archive)를 두어, crawlLinks가 모든 글에 닿게 한다.
  • Nuxt Content는 최신 버전을 쓴다. 미리 만들지 않은 페이지도 서버에서 정상으로 동작한다.

자세한 설정은 Nuxt 3 SEO 설정 정리에 있다.