为何'docusaurus'命令未被识别？求解决方法及错误详情

一、错误原因分析 #

你遇到的'docusaurus' is not recognized错误核心是版本不匹配：

• 全局安装的是Docusaurus v1.14.7，它的启动命令是docusaurus-start而非docusaurus start
• 项目本地依赖的是Docusaurus v2.4.1，v2的命令格式为docusaurus <command>，但全局未安装v2的CLI工具，直接执行docusaurus start会调用全局v1工具，导致命令不兼容。

二、启动错误的解决方法 #

以下三种方案按需选择：

方案1：使用本地项目的Docusaurus命令 #

在项目根目录执行：

npx docusaurus start

或在package.json的scripts中添加：

"scripts": {
  "start": "docusaurus start",
  "build": "docusaurus build"
}

之后直接运行：

yarn start

Yarn会自动优先使用本地node_modules/.bin下的v2命令，无需全局安装。

方案2：全局安装Docusaurus v2 CLI #

先卸载全局的v1版本：

yarn global remove docusaurus

再安装v2的CLI工具：

yarn global add @docusaurus/cli

之后即可直接在任意目录执行docusaurus start（确保项目为v2版本）。

方案3：清理全局依赖避免冲突 #

若不需要全局Docusaurus工具，直接卸载全局v1版本：

yarn global remove docusaurus

之后始终用方案1的本地命令启动项目即可。

三、正确的Docusaurus v2依赖配置 #

你的当前依赖包含大量非必需包（如webpack、eslint、jest等，Docusaurus v2已内置适配版本），基础v2项目依赖可精简如下：

最小化依赖示例 #

"devDependencies": {
  "@docusaurus/core": "^2.4.1",
  "@docusaurus/preset-classic": "^2.4.1",
  "@mdx-js/react": "^1.6.21",
  "@types/react": "^17.0.2"
},
"dependencies": {
  "react": "^17.0.2",
  "react-dom": "^17.0.2"
}

按需保留额外依赖 #

若需要特定功能，可保留对应依赖：

• @docusaurus/theme-mermaid：支持Mermaid图表
• rehype-katex/remark-math：支持数学公式
• @algolia/client-search：支持Algolia搜索
• AWS相关依赖：仅当需要S3部署等功能时保留

注意：不要手动安装webpack、eslint这类工具，否则可能与Docusaurus内置版本冲突。

四、让Yarn输出详细错误日志 #

执行命令时添加--verbose参数：

yarn start --verbose

或全局设置Yarn日志级别为详细：

yarn config set logLevel verbose

之后所有Yarn命令都会输出更详细的执行日志，便于排查问题。

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