인프런 커뮤니티 질문&답변
Markdown MDX 관련 질문입니다.
해결된 질문
작성
·
203
0
에러화면

/mdx-page 렌더링이 안됩니다...
작업 순서
패키지 설치
npm install @next/mdx @mdx-js/loader @mdx-js/react @types/mdxnext.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
안녕하세요! 🙂
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
안녕하세요, 인프런 AI 인턴입니다. 포팃님.
MDX 페이지를 렌더링하려 할 때 발생하는 이슈는 주로 설정이나 패키지 호환성 문제에서 비롯될 수 있습니다. 아래에 몇 가지 주요 원인과 해결 방법을 설명드리겠습니다.
문제 원인 및 해결 방법
Next.js와 Turbopack 문제:
Runtime Error와 관련된 메시지를 보면, Turbopack과 관련된 문제가 발생한 것 같습니다. Turbopack은 여전히 실험 기능이기 때문에 문제를 일으킬 수 있습니다.next dev --turbopack대신next dev로 다시 시도해보세요.
Dependencies 버전 호환성 확인:
react와react-dom의 버전이 안정 릴리스가 아닌19.0.0으로 설정되어 있습니다. 현재 안정 버전(2023년 10월 기준)은18.x.x입니다. 각 패키지가 React 19를 지원하지 않을 수 있습니다. 두 패키지를18.x.x버전으로 다운그레이드 해보세요.
npm install react@18 react-dom@18
타입 선언 버전 문제:
@types/mdx,@types/react,@types/react-dom등의 타입 패키지 버전이 React 버전과 호환되지 않을 수 있습니다.@types/react와@types/react-dom은18.x.x버전으로 맞추는 것이 좋습니다.
페이지 경로 및 설정 확인:
pageExtensions에md,mdx가 추가되어 있는 것은 올바른 설정입니다. 하지만app/mdx-page/page.mdx경로와 파일명이 맞는지, 혹시 오타는 없는지 다시 한 번 확인해 주세요.
Next.js 설정 파일 내 정의 오류 확인:
next.config.ts파일에서withMDX와nextConfig를 올바르게 병합했는지 확인합니다. 만약 MDX 설정이 올바르게 되지 않았다면, 기본적인next.config.js설정으로 돌아가 MDX 설정을 무효화한 상태로 테스트 해보는 것도 한 방법입니다.
참고자료 제공
다음 문서를 확인해 보시면 관련 문제의 다른 사례와 더 깊이 있는 설명을 보실 수 있습니다:
- Next.js MDX 설정 관련 공식 가이드
- React와 Next.js의 버전 호환성 문제를 해결하는 방법
저는 질문자님의 이해를 돕고자 지식공유자님의 기존 답변을 참고하여 유사한 답변 링크를 추천해드리고 있습니다.
현재 베타 기능으로 답변이 만족스럽지 않을 수 있는 점 양해 부탁드립니다. 🙏
추가적으로 궁금한 점이 있으시면, 이어서 질문해 주세요. 곧 지식공유자께서 답변해 주실 것입니다.





감사합니다!
Turbopack 없이 실행했더니 작동해서 넘어갔는데 의존성 버전 고정해서 해결하는 방법도 있었네요;;;
자세하게 설명해주셔서 감사합니다^^ 강의 너무 잘 보고 있습니다!ㅎㅎ