为什么选择 nextra 🤔

在 React 生态系统中，我对 SWR 这个网络请求库情有独钟。它不仅设计简洁优雅，功能也异常强大，已成为我所有项目的首选工具。

而 SWR 的官方文档网站正是基于 nextra 构建的。作为一个开源项目，其源代码完全托管在 github 上。 研究过源码后，我发现 nextra 不仅功能强大，而且使用简单，非常适合用来搭建我的个人博客。因此我决定采用它作为博客的技术方案。

nextra 的优点 ✨

基于 Next.js 构建

nextra 以 Next.js 作为底层框架，这让我们能够充分享受 Next.js 提供的强大功能和便利性。其中包括但不限于以下特性：

• 基于文件系统的智能路由系统，不需要手动配置路由，所有路由全部由 Next.js 自动生成，非常方便。

• 使用 Next.js Link 和 Next.js Image 智能链接预加载与优化, 内置的图片自动优化处理。

[Next.js Link](https://nextjs.org/docs/app/api-reference/components/link) 👉 <Link ...>
![nextra-image](https://nextra.site/assets/image.png) 👉 <Image ... />

• 灵活的静态与动态预渲染

支持 SSG、SSR、ISR 三种预渲染模式，可以根据不同的场景选择不同的预渲染模式。

使用简单，上手容易

nextra 主要使用 mdx 文件来编写文档。mdx 文件是一种将 markdown 和 React 组件混合在一起的文件格式，这对于 React 生态开发者来说非常友好， 即保留了 markdown 的简洁易用，又可以使用 React 组件来实现更复杂的功能。

响应式设计，支持多语言

nextra 在响应式设计方面表现出色，能够完美适配从手机到桌面的各种屏幕尺寸。此外，它还提供了优雅的多语言支持方案，只需通过简单的文件路径约定即可实现，例如：

• /en/hello.mdx 用于英文内容
• /zh/hello.mdx 用于中文内容

高效率语法高亮

nextra 采用了业界领先的 shiki 语法高亮引擎，能够完美支持包括 JavaScript、TypeScript、Python、Java 在内的数百种编程语言。 非常适合技术文档以及博客类网站使用。

function quickSort(arr: number[]): number[] {
  if (arr.length <= 1) return arr;
  const pivot = arr[Math.floor(arr.length / 2)];
  const left = arr.filter(x => x < pivot);
  const right = arr.filter(x => x > pivot);
  return [...quickSort(left), pivot, ...quickSort(right)];
}

全局搜索

nextra 基于 flexsearch 提供了强大的全文搜索功能。 通过这个高性能的搜索引擎，你可以轻松搜索文档中的所有内容，包括标题、描述、正文等。搜索结果即时呈现，帮助用户快速找到所需信息。 最令人惊喜的是，这个强大的搜索功能完全不需要任何配置，开箱即可使用。

使用 nextra 踩的坑 🕳️

虽然 nextra 使用很简单，但是有一个很大的坑，那就是 nextra 官方的 template 是以 v2 版本构建的， 而官方文档默认是 v3 版本的。

假如你不想使用最新版本，那就很简单，直接看 v2 版本的文档即可, 包括文章开头提到的 SWR 的文档网站 也是基于 v2 版本构建，你可以直接参考里面的代码。

但是爱折腾的我们，肯定想使用最新版本，首先确保：

• Node.js 版本 ≥ 18
• React 版本 ≥ 18
• Next.js 版本 ≥ 13

然后，请使用 next.config.mjs 文件或者在 package.json 文件中添加 "type": "module" 。

import nextra from 'nextra'
 
const withNextra = nextra({
 theme: 'nextra-theme-docs',
 themeConfig: './theme.config.jsx'
 // ... your Nextra config
})
 
export default withNextra({
 // ... your Next.js config
})

然后，_meta.json、_app.mdx 不再支持，需要换成 _meta.{js,jsx,ts,tsx}、_app.{js,jsx,ts,tsx} 文件。

最后 theme.config 里面有很多选项被移除或者更名，例如

• 移除了 useNextSeoProps 选项，直接在 head 里面配置
• editLink.text -> editLink.content
• footer.text -> footer.content

更改完这些配置后，就可以使用 nextra V3 版本了，如果你还有其他问题，可以参考 nextra 3.0 迁移指南

最后，V3 版本还有一个小问题。如果你的博客使用的是外部图片，那么在使用

这个特性时，不会获得 next/image 的优化，所以你需要自己使用 next/image 封装一个组件来优化图片。