Nextra 多文档路由配置实践指南

Nextra 作为一款基于 Next.js 的静态站点生成工具，以其优雅的文档风格和强大的功能受到开发者青睐。本文将深入探讨如何在一个 Nextra 项目中实现多文档集合并存的技术方案，帮助开发者解决实际项目中的复杂路由配置问题。

项目背景与需求分析

在真实项目开发中，我们常常需要维护多个独立的文档集合。例如：

• 商业计划文档（/docs/ 路径）
• 技术手册文档（/tech/ 路径）
• 自定义首页（/ 路径）

这些需求带来了以下技术挑战：

1. 需要保留完全自定义的 React 首页
2. 每个文档集合需要独立的路由前缀
3. 各文档集合需要保持各自的导航结构和样式一致性

核心解决方案

路由结构设计

正确的目录结构设计是解决问题的关键。推荐采用以下方案：

app/
├── [[...mdxPath]]/page.jsx → 改为 [...mdxPath]/page.jsx
├── page.tsx (自定义首页)
└── layout.jsx

关键修改点是将可选捕获路由 [[...mdxPath]] 改为必需捕获路由 [...mdxPath]，这解决了与根路径 / 的冲突问题。

内容目录组织

内容目录建议采用扁平化结构：

content/
├── docs/            # 商业文档
│   ├── index.mdx
│   └── glossary.mdx
└── tech/            # 技术文档
    ├── index.mdx
    └── api.mdx

配置调整

在 next.config.mjs 中设置：

const withNextra = nextra({
  contentDirBasePath: '/' // 从根目录读取内容
})

进阶技巧

自定义首页实现

虽然 Nextra 默认使用 index.mdx 作为首页，但可以通过以下方式实现完全自定义的 React 首页：

1. 保留 app/page.tsx 作为入口
2. 在 content/index.mdx 中添加重定向逻辑
3. 或者完全移除 content/index.mdx，仅依赖 app/page.tsx

多文档导航配置

通过 _meta.js 文件实现多文档导航：

export default {
  index: {
    display: 'hidden'
  },
  docs: {
    type: 'page',
    title: '商业计划书',
    display: 'children'
  },
  tech: {
    type: 'page',
    title: '技术手册',
    display: 'children'
  }
}

常见问题解决

路由冲突错误

当遇到类似错误时： You cannot define a route with the same specificity...

解决方案：

1. 检查是否同时存在 / 和 [[...mdxPath]] 路由
2. 将可选捕获路由改为必需捕获路由
3. 确保路由定义没有重复

静态生成参数缺失

对于错误： Page is missing param in generateStaticParams()

建议：

1. 检查 generateStaticParams 是否正确导出
2. 确认 contentDirBasePath 配置正确
3. 在开发模式下可暂时移除 output: 'export' 配置

最佳实践建议

1. 文档隔离原则：每个文档集合应保持完全独立，包括导航结构和样式
2. 渐进式配置：先实现基础路由，再逐步添加复杂功能
3. 组件化开发：即使使用 MDX 编写文档，也应将 UI 元素抽象为可复用组件
4. 类型安全：为 _meta.js 配置添加 TypeScript 类型定义，提高开发体验

通过本文介绍的方法，开发者可以在 Nextra 项目中灵活实现多文档集合并存的需求，同时保持代码的可维护性和扩展性。这种方案特别适合需要同时维护产品文档、技术文档和营销内容的中大型项目。