Docusaurus执行yarn build时出现EEXIST错误（index.html已存在）

问题背景 #

使用Docusaurus 3.5.2 + Node 22.5.1执行yarn build时，触发EEXIST错误，提示build/docs/index.html文件已存在，导致构建失败；但开发模式yarn start可正常运行。已尝试删除build目录、检查进程锁定、排查配置文件等操作，问题仍存在。

解决方案 #

1. 排查plugin-client-redirects配置冲突 #

报错日志明确提到“Redirect file creation error”，大概率是该插件的重定向规则与Docusaurus自动生成的docs/index.html冲突：

• 打开docusaurus.config.js，定位到plugin-client-redirects配置
• 检查redirects数组或createRedirects函数中，是否存在指向/docs/的重定向规则（比如从旧路径跳转到docs首页）
• 若存在冲突规则，可调整目标路径（如指向/docs/overview而非根路径），或修改插件的redirects生成逻辑，避免重复创建index.html文件

2. 检查第三方插件的路径重叠问题 #

你使用的docusaurus-plugin-typedoc等插件可能与Docusaurus核心的文档输出路径重叠：

• 临时禁用docusaurus-plugin-typedoc，执行yarn build验证是否还报错
• 若禁用后正常，调整Typedoc插件的输出路径配置，将其文档输出到docs/api这类子目录，避免直接覆盖docs根目录的index.html
• 同理排查其他第三方插件（如sass插件）是否存在异常的文件写入行为

3. 切换至兼容的Node LTS版本 #

Docusaurus 3.5.2官方推荐使用Node 18.x或20.x LTS版本，Node 22属于非LTS版本，可能存在文件系统操作兼容性问题：

• 使用nvm切换版本（示例为Node 20）：

  nvm install 20
  nvm use 20
  

• 重新执行yarn install和yarn build

4. 彻底清理构建缓存与旧文件 #

除手动删除build目录外，还需清理Docusaurus的内部缓存：

• 执行以下命令：

  yarn docusaurus clear
  rm -rf node_modules/.cache
  rm -rf build
  yarn build
  

5. 验证文件系统权限 #

部分情况下，文件权限异常会导致无法覆盖已存在的文件：

• Linux/macOS环境：执行chmod -R 755 ./确保项目目录权限正常
• Windows环境：右键项目目录，进入“属性”->“安全”选项卡，确认当前用户拥有完全控制权限

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