如何将Docusaurus嵌入大型ReactJS项目并通过react-scripts启动？

以下是实现单入口集成的具体步骤，无需单独运行Docusaurus服务，直接通过react-scripts start启动整个应用：

1. 安装Docusaurus依赖 #

在你的React项目根目录下执行：

npm install @docusaurus/core @docusaurus/preset-classic react-router-dom@5
# 说明：Docusaurus v2依赖react-router-dom v5，若项目使用v6，需做兼容处理或锁定v5版本

2. 创建Docusaurus基础目录结构 #

在项目根目录下新建必要的文件夹和文件：

your-react-app/
├── docs/               # 存放所有指南文档（.md/.mdx格式）
│   ├── intro.md
│   └── ...
├── docusaurus.config.js # Docusaurus核心配置文件
└── src/
    └── pages/          # 可选：存放Docusaurus自定义页面

3. 配置Docusaurus为嵌入模式 #

修改docusaurus.config.js，禁用独立服务器和默认路由，适配现有React项目的路由体系：

module.exports = {
  title: '应用指南',
  tagline: '快速上手应用功能',
  url: 'http://localhost:3000', // 匹配React项目本地地址
  baseUrl: '/guide/', // 指南板块的基础路由前缀
  onBrokenLinks: 'warn',
  onBrokenMarkdownLinks: 'warn',
  favicon: 'img/favicon.ico', // 可复用现有项目的favicon
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          routeBasePath: '/', // 让文档路由基于baseUrl，而非默认的/docs
          sidebarPath: require.resolve('./sidebars.js'), // 可选：配置侧边栏
        },
        theme: {
          customCss: require.resolve('./src/css/custom.css'), // 可选：自定义样式消除冲突
        },
      },
    ],
  ],
  // 关键：禁用Docusaurus独立路由系统，交给React路由接管
  plugins: [
    async function embedPlugin(context, options) {
      return {
        name: 'docusaurus-embed-plugin',
        async contentLoaded({ actions }) {
          // 跳过静态HTML生成，仅保留组件逻辑
        },
      };
    },
  ],
};

若需要侧边栏，新建sidebars.js文件：

module.exports = {
  tutorialSidebar: [
    {
      type: 'doc',
      id: 'intro', // 对应docs/intro.md文件
      label: '入门指南',
    },
    // 添加更多文档条目
  ],
};

4. 在React项目中引入Docusaurus组件 #

在项目的路由配置文件（如src/App.js或src/routes/index.js）中，添加指南板块的路由，直接引入Docusaurus根组件：

import React from 'react';
import { BrowserRouter as Router, Routes, Route } from 'react-router-dom';
import Dashboard from './pages/Dashboard';
import Auth from './pages/Auth';
// 引入Docusaurus核心组件和配置
import DocusaurusApp from '@docusaurus/core/lib/client/app';
import docusaurusConfig from '../docusaurus.config';

function App() {
  return (
    <Router>
      <Routes>
        <Route path="/" element={<Dashboard />} />
        <Route path="/auth" element={<Auth />} />
        {/* 指南板块路由，匹配baseUrl下的所有子路径 */}
        <Route path="/guide/*" element={<DocusaurusApp config={docusaurusConfig} />} />
      </Routes>
    </Router>
  );
}

export default App;

5. 调整react-scripts的Webpack配置（关键） #

react-scripts默认不支持MDX编译和Docusaurus的静态资源处理，需用react-app-rewired修改配置：

首先安装依赖：

npm install react-app-rewired customize-cra @docusaurus/mdx-loader

在项目根目录新建config-overrides.js：

const { override, addWebpackModuleRule } = require('customize-cra');

module.exports = override(
  // 添加MDX文件编译规则
  addWebpackModuleRule({
    test: /\.mdx?$/,
    use: [
      'babel-loader',
      {
        loader: '@docusaurus/mdx-loader',
        options: {
          remarkPlugins: [],
          rehypePlugins: [],
        },
      },
    ],
  }),
  // 处理Docusaurus静态资源
  addWebpackModuleRule({
    test: /\.(png|jpe?g|gif|svg|woff|woff2|ttf|eot|ico)$/,
    loader: 'file-loader',
    options: {
      name: 'static/media/[name].[hash:8].[ext]',
    },
  })
);

修改package.json中的启动/构建命令：

{
  "scripts": {
    "start": "react-app-rewired start",
    "build": "react-app-rewired build",
    "test": "react-app-rewired test",
    "eject": "react-scripts eject"
  }
}

6. 测试与调试 #

运行npm start启动应用，访问http://localhost:3000/guide即可查看Docusaurus指南板块，原有授权、仪表盘功能不受影响。

注意事项：

• 若项目使用react-router-dom v6，需确保Docusaurus路由适配v6规则，可通过调整路径匹配逻辑实现兼容
• Docusaurus主题样式可能与现有项目冲突，可通过customCss自定义样式覆盖
• 构建时，Docusaurus的静态资源会自动打包到React项目的build目录，无需额外处理

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