Docusaurus 3.5设置baseUrl为/docs/构建失败问题求助

• 检查内置路由冲突：Docusaurus 默认将 docs 作为文档板块的路由前缀，当你把 baseUrl 设置为 /docs/ 时，会和内置文档路由产生嵌套冲突（比如默认文档路径 /docs/xxx 会变成 /docs/docs/xxx），触发路由解析错误导致构建失败。

• 修改文档板块的 routeBasePath：默认配置里文档板块的 routeBasePath 是 docs，和 baseUrl 的 /docs/ 冲突。可以将其改为其他名称，示例配置：

  // docusaurus.config.js
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          routeBasePath: 'guides', // 替换默认的'docs'
        },
      },
    ],
  ],
  

• 校验静态资源引用：项目中如果有硬编码的静态资源路径（如图片、脚本），使用 /docs/ 作为 baseUrl 后可能无法正确解析。确保所有静态资源通过 require 或 useBaseUrl 辅助函数引用。

• 查看构建错误日志：运行 docusaurus build 时，仔细查看终端输出的错误详情，日志会明确指出冲突点或资源缺失问题，是定位问题的关键依据。

• 排查第三方插件/主题冲突：如果使用了第三方插件或自定义主题，可能存在硬编码的 /docs/ 路由逻辑，导致和 baseUrl 设置冲突。可以临时禁用第三方插件，重新构建验证是否是插件导致的问题。

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