Redocusaurus多API显示问题：npm run build时Docusaurus SSR渲染失败

排查路径配置问题 #

• 核对docusaurus.config.js中Redocusaurus插件的specPath配置，改用绝对路径替代相对路径，避免SSR环境下路径解析差异。可借助Node.js的path模块拼接路径：

  const path = require('path');
  
  module.exports = {
    plugins: [
      [
        'redocusaurus',
        {
          specs: [
            {
              spec: path.resolve(__dirname, 'apiConfigFiles/api1.yml'),
              route: '/api/api1/',
            },
            {
              spec: path.resolve(__dirname, 'apiConfigFiles/api2.yml'),
              route: '/api/api2/',
            },
          ],
        },
      ],
    ],
  };
  

• 检查yml文件名大小写，本地Windows环境不区分大小写，但构建环境（如Linux）会严格校验，确保配置中的文件名与实际文件完全一致。

处理SSR环境下的文件读取 #

• 若API定义为动态生成或异步加载，需确保在SSR阶段同步获取文件内容，避免在组件中使用fs.readFile这类异步方法，应在插件配置阶段完成所有spec文件的加载。
• 将apiConfigFiles文件夹加入Docusaurus静态资源配置，确保构建时文件被正确复制：

  module.exports = {
    staticDirectories: ['public', 'apiConfigFiles'],
  };
  

检查版本兼容性 #

• 确认Redocusaurus与Docusaurus版本匹配（如Redocusaurus v2.x需搭配Docusaurus v2.x），执行命令查看当前版本：

  npm list @docusaurus/core redocusaurus
  

• 若版本不兼容，升级或降级至匹配版本：

  npm install redocusaurus@latest @docusaurus/core@latest
  

清理缓存后重新构建 #

• 清理Docusaurus缓存文件，避免旧缓存干扰：

  npm run clear
  

• 重新执行构建命令：

  npm run build
  

排查路由冲突 #

• 检查是否有其他插件或自定义页面的路由与Redocusaurus配置的API路由重叠（如/api/api1/），确保每个API的route配置唯一且不与现有路由冲突。

内容的提问来源于stack exchange，提问作者Mateusz Matuś Kowalski