探索Next.js静态站点框架Nextra的功能和实现原理

pnpm i next react react-dom nextra nextra-theme-docs

const withNextra = require('nextra')({
    // 主题名称
    theme: 'nextra-theme-docs',
    // 主题配置，指定主题配置文件
    themeConfig: './theme.config.jsx'
})
 
const nextConfig = {
    // next 本身配置
}
 
// withNextra 的作用其实就是添加 next 配置。
module.exports = withNextra(nextConfig);

./packages
├── nextra 核心库
├── nextra-theme-blog 博客主题
└── nextra-theme-docs 文档主题

// packages/nextra-theme-docs/src/index.tsx
 
// 提供给 Nextra 核心库使用的布局组件
export default function Layout({
  children,
  ...context
}: NextraThemeLayoutProps): ReactElement {
  return (
    <ConfigProvider value={context}>
      <InnerLayout {...context.pageOpts}>{children}</InnerLayout>
    </ConfigProvider>
  )
}
 
// 提供给开发者使用的hook，用于获取主题的配置信息和页面的FrontMatter信息
export { useConfig, PartialDocsThemeConfig as DocsThemeConfig }
// 提供给开发者使用的hook，就是 @mdx-js/react 中的组件，Nextra 核心库会使用，但并不依赖主题库中的导出。
export { useMDXComponents } from 'nextra/mdx'
// 提供给开发者使用的hook，内部主题色系就是使用的 next-themes
export { useTheme } from 'next-themes'
// 提供给开发者使用的组件，部分组件在布局组件中都有用到，不是提供给 Nextra 核心库
export {
  Bleed,
  Callout,
  Collapse,
  NotFoundPage,
  ServerSideErrorPage,
  Steps,
  Tabs,
  Tab,
  Cards,
  Card,
  FileTree,
  Navbar,
  SkipNavContent,
  SkipNavLink,
  ThemeSwitch
} from './components'

// packages/nextra/src/index.js
// 默认页面文件后缀
const DEFAULT_EXTENSIONS = ['js', 'jsx', 'ts', 'tsx']
 
const nextra = (themeOrNextraConfig, themeConfig) =>
  function withNextra(nextConfig = {}) {
    // 主题文件可通过两个参数传入，或者一个参数传入
    const nextraConfig = {
      ...DEFAULT_CONFIG,
      ...(typeof themeOrNextraConfig === 'string'
        ? { theme: themeOrNextraConfig, themeConfig }
        : themeOrNextraConfig)
    }
    
    // 下面两行是处理多语言的逻辑
    const locales = nextConfig.i18n?.locales || DEFAULT_LOCALES
    const nextraPlugin = new NextraPlugin({ ...nextraConfig, locales })
    
    // 添加 rewrites 来护理 _meta 文件的解析
    const rewrites = async () => {
      const rules = [
        {
          source: '/:path*/_meta',
          destination: '/404'
        }
      ]
      // 兼容外部的 rewrites
      if (nextConfig.rewrites) {
        const originalRewrites = await nextConfig.rewrites()
        if (Array.isArray(originalRewrites)) {
          return [...originalRewrites, ...rules]
        }
        return {
          ...originalRewrites,
          beforeFiles: [...(originalRewrites.beforeFiles || []), ...rules]
        }
      }
 
      return rules
    }
    
    // 这里即将验证前面说的 nextra 本身就是 Next.js 的一个插件，用于处理 markdown 文件，加载新的文件格式就需要注入新的 loader，这里就是 loader 的配置参数
    const nextraLoaderOptions = {
      ...nextraConfig,
      // ...其他配置省略，不影响主流程
    }
    
    // 返回处理后的 next config 配置
    return {
      ...nextConfig,
      rewrites,
      // 扩展页面文件后缀
      pageExtensions: [
        ...(nextConfig.pageExtensions || DEFAULT_EXTENSIONS),
        ...MARKDOWN_EXTENSIONS // ['md', 'mdx']
      ],
      webpack(config, options) {
        // 此处处理 plugin，现在有多语言plugin和搜索plugin
        if (options.nextRuntime !== 'edge' && options.isServer) {
          config.plugins ||= []
          config.plugins.push(nextraPlugin)
          // 搜索功能实现就于此处有关
          if (nextraConfig.flexsearch) {
            const nextraSearchPlugin = new NextraSearchPlugin({})
            config.plugins.push(nextraSearchPlugin)
          }
        }
        
        config.module.rules.push(
          {
            // 匹配非页面的 Markdown，也就是可以把 Markdown 当成组件使用，但我试了一下会报错
            test: MARKDOWN_EXTENSION_REGEX, // /\.mdx?$/
            issuer: request => !!request || request === null,
            use: [
              options.defaultLoaders.babel,
              {
                loader: 'nextra/loader',
                options: nextraLoaderOptions
              }
            ]
          },
          {
            // 匹配 Markdown 编写的页面
            test: MARKDOWN_EXTENSION_REGEX, // /\.mdx?$/
            issuer: request => request === '',
            use: [
              options.defaultLoaders.babel,
              {
                loader: 'nextra/loader',
                options: {
                  ...nextraLoaderOptions,
                  isPageImport: true // 有这个标志的才会显示 Layout
                }
              }
            ]
          },
          {
            // 匹配 _meta 文件，也就是不仅支持 json ，还支持使用js的方式进行使用，因为 json 不需要 loader，因此这里不匹配 json
            test: /_meta(\.[a-z]{2}-[A-Z]{2})?\.js$/,
            issuer: request => !request,
            use: [
              options.defaultLoaders.babel,
              {
                loader: 'nextra/loader',
                options: {
                  isMetaImport: true
                }
              }
            ]
          }
        )
 
        return nextConfig.webpack?.(config, options) || config
      }
    }
  }
 
module.exports = nextra

// packages/nextra/src/loader.ts
 
// 全局部分代码有一些编译前的文件检查
 
// 核心
async function loader(
  context: LoaderContext<LoaderOptions>,
  source: string
): Promise<string> {
  const {
    isMetaImport = false,
    isPageImport = false,
    theme,
    themeConfig,
    locales,
    flexsearch,
    // ...
  } = context.getOptions()
 
  // 不解析 _meta.js，_meta.js 后面动态解析
  if (isMetaImport) {
    return 'export default () => null'
  }
 
  // ...省略掉一些文件过滤和文件依赖处理事项
  
  // 这里是最核心的代码编译部分，匹配到的文件都将使用 compileMdx 去进行编译处理，并返回组装页面需要的内容
  const {
    result,
    headings,
    title,
    frontMatter,
    structurizedData,
    searchIndexKey,
    hasJsxInH1,
    readingTime
  } = await compileMdx(
    source,
    {
      mdxOptions: {
        ...mdxOptions,
        jsx: true,
        outputFormat: 'program',
        format: 'detect'
      },
      readingTime: _readingTime,
      defaultShowCopyCode,
      staticImage,
      flexsearch,
      latex,
      codeHighlight,
      route: pageNextRoute,
      locale
    },
    {
      filePath: mdxPath,
      useCachedCompiler: false, // TODO: produce hydration errors or error - Create a new processor first, by calling it: use `processor()` instead of `processor`.
      isPageImport
    }
  )
 
  // 不是页面级组件，则直接返回, 不需要添加到 layout。
  if (!isPageImport) {
    return result
  }
  
  // 后面的的部分就是使用编译得到的内容，进行拼接成一个编译后的页面级别的 js 代码
  // 其中涉及到了多语言/frontMatter/layout/路由/页面标题等等
}