Docusaurus启动报错：plugins[0]配置值无效，请求协助

问题背景 #

此前可正常运行的Docusaurus 2.4.0项目，未做任何修改的情况下执行npm run start，出现以下报错：

E:\ngDocs>npm run start

> ngdocs@0.0.0 start
> docusaurus start

[INFO] Starting the development server...
[ERROR] Error:  => Bad Docusaurus plugin value plugins[0].
Example valid plugin config:
{
  plugins: [
    ["@docusaurus/plugin-content-docs",options],
    "./myPlugin",
    ["./myPlugin",{someOption: 42}],
    function myPlugin() { },
    [function myPlugin() { },options]
  ],
};


    at validateConfig (E:\ngDocs\node_modules\@docusaurus\core\lib\server\configValidation.js:228:15)
    at loadSiteConfig (E:\ngDocs\node_modules\@docusaurus\core\lib\server\config.js:40:62)
    at async loadContext (E:\ngDocs\node_modules\@docusaurus\core\lib\server\index.js:31:63)
    at async load (E:\ngDocs\node_modules\@docusaurus\core\lib\server\index.js:74:21)
    at async Command.start (E:\ngDocs\node_modules\@docusaurus\core\lib\commands\start.js:44:19)
[INFO] Docusaurus version: 2.4.0
Node version: v16.17.0

解决方案 #

• 检查docusaurus.config.js中plugins数组的格式
  打开项目根目录的docusaurus.config.js，定位到plugins配置项，确认第一项的格式符合Docusaurus要求：

  • 合法的插件配置格式包括：
    1. 字符串（插件包名或本地插件路径）
    2. 数组（[插件名/路径, 配置对象]）
    3. 函数形式的插件
    4. 数组包裹的函数插件+配置（[函数插件, 配置对象]）
  • 常见错误：将插件配置写成单独的对象而非数组，比如错误写法：

    plugins: [{
      plugin: '@docusaurus/plugin-content-docs',
      options: { path: 'docs' }
    }]
    

    正确写法应为：

    plugins: [['@docusaurus/plugin-content-docs', { path: 'docs' }]]
    

• 清理依赖缓存并重装依赖
  依赖缓存损坏可能导致配置解析异常，执行以下命令：

  # Windows系统
  del /s /q node_modules
  del package-lock.json
  npm install
  
  # macOS/Linux系统
  rm -rf node_modules package-lock.json
  npm install
  

  重装完成后再次尝试npm run start。

• 排查配置文件的意外变更
  即使未手动修改，编辑器自动格式化、版本控制误提交都可能改变配置文件内容。如果使用Git，执行git diff docusaurus.config.js查看plugins部分是否有意外修改，如有则回退到正确版本。

• 验证Node版本兼容性
  Docusaurus 2.4.0支持Node 14、16、18版本，当前使用的v16.17.0符合要求，但可以尝试切换到对应大版本的最新LTS版本（比如v16.20.2），通过nvm等版本管理工具切换后重新启动项目。

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