Mdx Next.js
Next.js + MDX 部落格
TL;DRNext.js + MDX 兩條路:官方 @next/mdx(輕量、純 file-based)vs Contentlayer(較重、有 type-safe metadata 但 2024 中已停更)。2026 年推薦走官方 @next/mdx 或 next-mdx-remote。
三種主流做法對比
| 做法 | 安裝難度 | type 支援 | 維護狀態 | 適合 |
|---|---|---|---|---|
@next/mdx | ⭐ 簡單 | 手動 | ✅ 官方維護 | 文件站、簡單部落格 |
next-mdx-remote | ⭐⭐ 中 | 手動 | ✅ Vercel 維護 | 動態載入 MDX(CMS / DB) |
Contentlayer | ⭐⭐⭐ 較重 | 自動產生 | ⚠️ 2024 停更 | (已不推薦新專案) |
方法 1:@next/mdx(官方推薦)
npm install @next/mdx @mdx-js/loader @mdx-js/react
// next.config.mjs
import nextMDX from '@next/mdx';
const withMDX = nextMDX({
extension: /\.mdx?$/,
});
export default withMDX({
pageExtensions: ['js', 'jsx', 'mdx', 'ts', 'tsx'],
});
然後 app/blog/my-post.mdx 就會自動變成 /blog/my-post 路由。
# Hello MDX
可以混 React 元件:
import { Counter } from '@/components/Counter';
<Counter />
適合誰部落格 / 文件站 / 內容寫死在 repo 裡的場景。簡單、零依賴,但要資料庫驅動的內容就用方法 2。
方法 2:next-mdx-remote(動態載入)
npm install next-mdx-remote
import { MDXRemote } from 'next-mdx-remote/rsc';
import { compileMDX } from 'next-mdx-remote/rsc';
async function getPost(slug: string) {
// 從 DB / CMS / API 拿 markdown 字串
const source = await fetchFromCMS(slug);
return source;
}
export default async function Page({ params }) {
const source = await getPost(params.slug);
return <MDXRemote source={source} components={{ Counter }} />;
}
適合內容存 DB / CMS / Notion 的情境,RSC 模式直接 server 端編譯。
方法 3:Contentlayer(已停更,不推薦新專案)
維護狀態Contentlayer 在 2024 年中起停止維護,有相容性問題。原 fork: contentlayer2 由社群繼續維護,但生態已分裂,新專案請避免。
舊專案如果還在用,可以考慮遷移到 @next/mdx。
frontmatter 處理
MDX 不原生支援 frontmatter,要加 gray-matter:
import matter from 'gray-matter';
import fs from 'fs';
const source = fs.readFileSync('post.mdx', 'utf-8');
const { content, data } = matter(source);
// data.title / data.date / data.tags 等
常見需求:語法高亮
npm install rehype-pretty-code shiki
// next.config.mjs
import nextMDX from '@next/mdx';
import rehypePrettyCode from 'rehype-pretty-code';
const withMDX = nextMDX({
extension: /\.mdx?$/,
options: {
rehypePlugins: rehypePrettyCode, { theme: 'github-dark' },
},
});
shiki 是現代首選(VS Code 同款引擎、壓縮後體積小、build time 渲染)。
參考資料