Markdown MDX 관련 질문입니다.

에러화면

• /mdx-page 렌더링이 안됩니다...

작업 순서

• 패키지 설치

  npm install @next/mdx @mdx-js/loader @mdx-js/react @types/mdx

• next.config.ts

  import type { NextConfig } from 'next';
  import createMDX from '@next/mdx';
  
  const nextConfig: NextConfig = {
    /* config options here */
    // experimental: {
    //   typedRoutes: true,
    // },
    images: {
      remotePatterns: [
        {
          hostname: 'picsum.photos',
        },
        {
          hostname: 'images.unsplash.com',
        },
        {
          hostname: 'www.notion.so',
        },
        {
          hostname: 'prod-files-secure.s3.us-west-2.amazonaws.com',
        },
      ],
    },
    pageExtensions: ['js', 'jsx', 'md', 'mdx', 'ts', 'tsx'],
  };
  
  const withMDX = createMDX({
    // Add markdown plugins here, as desired
  });
  
  // Merge MDX config with Next.js config
  export default withMDX(nextConfig);
  

• mdx-components.tsx

  import type { MDXComponents } from 'mdx/types';
  
  export function useMDXComponents(components: MDXComponents): MDXComponents {
    return {
      ...components,
    };
  }

• app/mdx-page/page.mdx

  # Welcome to my MDX page!
  
  This is some **bold** and _italics_ text.
  
  This is a list in markdown:
  
  - One
  - Two
  - Three
  
  Checkout my React component:

• package.json

  {
    "name": "notion-blog-nextjs",
    "version": "0.1.0",
    "private": true,
    "scripts": {
      "dev": "next dev --turbopack",
      "build": "next build",
      "start": "next start",
      "lint": "next lint",
      "lint:fix": "next lint --fix",
      "format": "prettier --write ."
    },
    "dependencies": {
      "@mdx-js/loader": "^3.1.0",
      "@mdx-js/react": "^3.1.0",
      "@next/mdx": "^15.3.2",
      "@notionhq/client": "^3.0.1",
      "@radix-ui/react-select": "^2.2.4",
      "@radix-ui/react-separator": "^1.1.6",
      "@radix-ui/react-slot": "^1.2.2",
      "@types/mdx": "^2.0.13",
      "class-variance-authority": "^0.7.1",
      "clsx": "^2.1.1",
      "date-fns": "^4.1.0",
      "lucide-react": "^0.507.0",
      "next": "15.2.5",
      "postcss": "^8.5.3",
      "react": "^19.0.0",
      "react-dom": "^19.0.0",
      "react-icons": "^5.5.0",
      "tailwind-merge": "^3.2.0"
    },
    "devDependencies": {
      "@eslint/eslintrc": "^3",
      "@eslint/js": "^9.26.0",
      "@tailwindcss/postcss": "^4.1.5",
      "@types/node": "^20",
      "@types/react": "^19",
      "@types/react-dom": "^19",
      "eslint": "^9",
      "eslint-config-next": "15.2.5",
      "eslint-config-prettier": "^10.1.2",
      "globals": "^16.0.0",
      "prettier": "^3.5.3",
      "prettier-plugin-tailwindcss": "^0.6.11",
      "tailwindcss": "^4.1.5",
      "tw-animate-css": "^1.2.9",
      "typescript": "^5"
    }
  }
  

답변 2

1

짐코딩

2025-05-12T06:06:34.038Z

안녕하세요! 🙂

Next.js에서 MDX 페이지 에러 트러블슈팅

저도 테스트해 보니 Next.js 프로젝트에서 MDX 페이지가 갑자기 작동하지 않는 현상을 확인할 수 있었습니다. 문제와 해결책에 대해 자세히 설명드리겠습니다.

문제 상황

프로젝트에서 app/mdx-page/page.mdx 파일을 생성하여 MDX 페이지를 구현했습니다. 이전에는 정상적으로 작동했지만, 다시 테스트하니 다음과 같은 오류가 발생했습니다:

Error: An unexpected Turbopack error occurred. Please see the output of next dev for more details.

 

원인 분석

문제의 근본 원인은 의존성 패키지 버전 관리에 있었습니다. package.json 파일을 확인해보면:

...
"@next/mdx": "^15.1.7"
...

여기서 ^ 기호는 semver(시맨틱 버전) 규칙에 따라 "15.1.7 이상, 16.0.0 미만"의 모든 버전을 허용한다는 의미입니다. 문제는 자동으로 업데이트된 버전에서 Turbopack과의 호환성 이슈가 발생했기 때문입니다.

해결 방법

이 문제를 해결하는 두 가지 효과적인 방법이 있습니다:

1. 의존성 버전 고정하기

"@next/mdx": "15.1.7"

^ 기호를 제거하여 정확히 15.1.7 버전을 사용하도록 고정합니다. 이렇게 하면 예기치 않은 버전 업데이트로 인한 호환성 문제를 방지할 수 있습니다.

2. Turbopack 없이 개발 서버 실행하기

npx next dev  # --turbopack 플래그 없이 실행

또는 package.json에 별도 명령어를 추가하여 유연하게 사용할 수 있습니다:

"scripts": {
  "dev": "next dev --turbopack",
  "dev:webpack": "next dev",  // npm run dev:webpack으로 실행
  "build": "next build",
  "start": "next start",
  "lint": "next lint",
  "lint:fix": "next lint --fix",
  "format": "prettier --write ."
}

추가 팁

MDX 테스트 페이지는 임시 용도로만 사용하고, 실제 블로그 상세 페이지는 다른 방식으로 구현할 예정입니다. 그렇기 때문에 간단히 Turbopack 없이 테스트하는 것이 더 효율적일 수 있습니다.

 

위 해결방법으로 진행하면 아래 처럼 잘 나오는 걸 확인할 수 있습니다 🙂

 

0

포팃

2025-05-12T13:58:58.156Z

감사합니다!
Turbopack 없이 실행했더니 작동해서 넘어갔는데 의존성 버전 고정해서 해결하는 방법도 있었네요;;;

자세하게 설명해주셔서 감사합니다^^ 강의 너무 잘 보고 있습니다!ㅎㅎ

0

인프런 AI 인턴

2025-05-11T03:31:23.192Z

안녕하세요, 인프런 AI 인턴입니다. 포팃님.

MDX 페이지를 렌더링하려 할 때 발생하는 이슈는 주로 설정이나 패키지 호환성 문제에서 비롯될 수 있습니다. 아래에 몇 가지 주요 원인과 해결 방법을 설명드리겠습니다.

문제 원인 및 해결 방법

1. Next.js와 Turbopack 문제:

   • Runtime Error와 관련된 메시지를 보면, Turbopack과 관련된 문제가 발생한 것 같습니다. Turbopack은 여전히 실험 기능이기 때문에 문제를 일으킬 수 있습니다. next dev --turbopack 대신 next dev로 다시 시도해보세요.
     

2. Dependencies 버전 호환성 확인:

   • react와 react-dom의 버전이 안정 릴리스가 아닌 19.0.0으로 설정되어 있습니다. 현재 안정 버전(2023년 10월 기준)은 18.x.x입니다. 각 패키지가 React 19를 지원하지 않을 수 있습니다. 두 패키지를 18.x.x 버전으로 다운그레이드 해보세요.
     

   npm install react@18 react-dom@18

3. 타입 선언 버전 문제:

   • @types/mdx, @types/react, @types/react-dom 등의 타입 패키지 버전이 React 버전과 호환되지 않을 수 있습니다. @types/react와 @types/react-dom은 18.x.x 버전으로 맞추는 것이 좋습니다.
     

4. 페이지 경로 및 설정 확인:

   • pageExtensions에 md, mdx가 추가되어 있는 것은 올바른 설정입니다. 하지만 app/mdx-page/page.mdx 경로와 파일명이 맞는지, 혹시 오타는 없는지 다시 한 번 확인해 주세요.
     

5. Next.js 설정 파일 내 정의 오류 확인:

   • next.config.ts 파일에서 withMDX와 nextConfig를 올바르게 병합했는지 확인합니다. 만약 MDX 설정이 올바르게 되지 않았다면, 기본적인 next.config.js 설정으로 돌아가 MDX 설정을 무효화한 상태로 테스트 해보는 것도 한 방법입니다.
     

참고자료 제공

다음 문서를 확인해 보시면 관련 문제의 다른 사례와 더 깊이 있는 설명을 보실 수 있습니다:
- Next.js MDX 설정 관련 공식 가이드
- React와 Next.js의 버전 호환성 문제를 해결하는 방법

저는 질문자님의 이해를 돕고자 지식공유자님의 기존 답변을 참고하여 유사한 답변 링크를 추천해드리고 있습니다.
현재 베타 기능으로 답변이 만족스럽지 않을 수 있는 점 양해 부탁드립니다. 🙏
추가적으로 궁금한 점이 있으시면, 이어서 질문해 주세요. 곧 지식공유자께서 답변해 주실 것입니다.