Docusaurus 构建失败，index.html 出现 EEXIST 错误

Question

我在尝试使用yarn build 构建我的Docusaurus 项目时遇到错误。构建过程失败，并出现 index.html 文件的 EEXIST 文件已存在错误。此问题不会在开发模式（纱线启动）期间发生，但在生产构建时始终会出现。我正在使用 Docusaurus 版本 3.5.2 和 Node 版本 22.5.1。

以下是我的 package.json 依赖项的相关部分：

Docusaurus 软件包，如 @docusaurus/core、@docusaurus/plugin-client-redirects 等，版本 3.5.2 AWS Amplify 相关包 TypeScript 版本 5.0.3 各种插件，如 docusaurus-plugin-sass、docusaurus-plugin-typedoc

错误日志如下：

[ERROR] Redirect file creation error for "build/docs/index.html".
[ERROR] Error: Unable to build website for locale en.
    at tryToBuildLocale (node_modules/@docusaurus/core/lib/commands/build.js:54:19)
    at async node_modules/@docusaurus/core/lib/commands/build.js:65:9
    at async mapAsyncSequential (node_modules/@docusaurus/utils/lib/jsUtils.js:21:24)
    at async Command.build (node_modules/@docusaurus/core/lib/commands/build.js:63:5) {
  cause: [Error: EEXIST: file already exists, open 'build/docs/index.html'] {
    errno: -17,
    code: 'EEXIST',
    syscall: 'open',
    path: 'build/docs/index.html'
  }
}

我尝试过的步骤：

• 确保没有进程锁定index.html 文件。
• 在运行yarn build 之前手动删除构建目录。 任何有关如何解决此问题的建议将不胜感激。谢谢！

我尝试通过确保没有进程锁定 index.html 文件并在尝试重建项目之前手动删除构建目录来解决该问题。我还检查了 docusaurus.config.js 和相关设置文件中是否有任何可能导致文件路径冲突的错误配置。

Answer 1

我通过调整 Docusaurus 配置文件中的重定向设置成功解决了构建错误。该问题源于重叠的重定向规则，这些规则在构建过程中导致了冲突。

问题详情：

EEXIST 错误表明构建过程正在尝试创建已存在的文件。发生这种情况是因为 @docusaurus/plugin-client-redirects 配置中存在两个重定向，它们基本上从非常相似的来源指向相同的目标：

[
  '@docusaurus/plugin-client-redirects',
  {
    redirects: [
      {
        to: '/docs/intro',
        from: '/docs',
      },
      {
        to: '/docs/intro',
        from: '/docs/',
      },
    ],
  },
]

上述设置尝试将 /docs 和 /docs/ 重定向到 /docs/intro，这可能会导致在构建过程中被视为 EEXIST 错误的文件处理冲突。

解决方案实施：

为了解决此问题，我从配置中删除了冗余重定向：

[
  '@docusaurus/plugin-client-redirects',
  {
    redirects: [
      {
        to: '/docs/intro',
        from: '/docs',
      },
    ],
  },
]

通过仅保留一个重定向规则，冲突得到解决，从而使构建能够成功完成而不会出现错误。