如何在Next.js中以路由形式集成Docusaurus文档站点

DevOps 小满

2026-9-2

Next.js应用承载/docs文档页的实现方案

Docusaurus集成方案

Docusaurus本身是独立的React静态站点框架，无法直接作为组件嵌入Next.js应用，但可以通过路径映射的方式实现无感知集成，生产环境常用两种实现方式：

静态产物嵌入（适合文档更新频率低的场景）
在项目内新建独立目录初始化Docusaurus，将Docusaurus的baseUrl配置为/docs/，构建时把Docusaurus的静态产物直接输出到Next.js的public/docs目录。Next.js默认会将/docs/*路径映射到public目录下的对应静态资源，不需要额外改路由配置，部署时和主站一起打包即可，用户访问时完全感知不到是两套应用。
注意要对齐主站和Docusaurus的导航、页脚风格，同时保持两边的斜杠规则配置一致，避免静态资源加载404。
重写转发独立部署（适合文档需要独立迭代的场景）
将Docusaurus作为独立服务部署在内网可访问的地址，在Next.js配置文件中添加路径重写规则，把所有/docs前缀的请求转发到Docusaurus服务：
```
// next.config.js
module.exports = {
  async rewrites() {
    return [
      {
        source: '/docs/:path*',
        destination: 'http://内部Docusaurus服务地址/:path*',
      },
    ]
  },
}
```
这种方式下主站和文档站可以独立发版，文档更新不需要重新部署整个Next.js应用，用户侧无感知。

如果不想维护两套独立的构建、部署逻辑，可以直接用Next.js生态的文档方案，天然和现有项目兼容：

Nextra：Next.js生态最成熟的文档站点生成器，直接作为插件接入现有项目，只需要把mdx文档放到app/docs（App Router）或pages/docs（Pages Router）目录下，自动生成侧边栏、路由、代码高亮、全文搜索、多版本文档等能力，和主站共享样式、组件、鉴权逻辑，接入成本极低。
原生MDX自建：如果文档体量小、自定义需求高，可以直接在Next.js中开启MDX支持，自行实现简单的侧边栏、目录导航组件，md/mdx文件直接作为路由页面，没有额外依赖。
Contentlayer + Next.js：用Contentlayer把本地md/mdx文档处理成类型安全的结构化数据，省去手动解析文档内容、生成静态路径的工作量，灵活度高于封装好的文档框架，适合需要自定义文档渲染逻辑的场景。

如果文档需要登录鉴权、和主站用户态打通，优先选择Next.js原生生态的方案，不需要额外处理跨应用的鉴权同步问题。

内容的提问来源于stack exchange，提问作者Bhupendra