Docker容器构建Docusaurus时提示“docusaurus: not found”问题排查

问题场景 #

本地通过Docker容器构建Docusaurus站点，执行以下命令启动容器：

docker run -it --rm --name doc-lab --mount type=bind,source=D:\work\some_path,target=/target_path -p 3000:3000 doc-lab

容器启动后在终端执行构建命令：

npm --prefix=/target_path run build

报错信息：

docusaurus: not found

已确认容器内/target_path目录存在，但重复执行命令仍报相同错误，需解决问题以成功构建并通过localhost访问站点。

可能的原因及解决办法 #

1. 容器内未安装项目依赖

你的doc-lab镜像大概率是基础Node镜像，没有提前安装Docusaurus相关依赖；或者挂载目录后，项目根目录下没有node_modules文件夹。

• 解决步骤：
  先进入绑定目录安装依赖：

  cd /target_path
  npm install
  

  依赖安装完成后再执行构建：

  npm run build
  

2. 构建命令依赖全局Docusaurus

如果项目package.json里的build命令直接调用了全局的docusaurus命令，但容器内没全局安装Docusaurus CLI。

• 解决二选一：
  • 全局安装Docusaurus：

    npm install -g @docusaurus/core@latest @docusaurus/preset-classic@latest
    

  • 修改项目package.json的scripts，使用本地依赖执行：

    "scripts": {
      "build": "npx docusaurus build"
    }
    

    或者直接调用本地bin文件：

    ./node_modules/.bin/docusaurus build
    

3. Windows路径挂载的权限/同步问题

Windows系统挂载本地目录到容器时，可能出现文件权限不足，导致容器无法读取node_modules/.bin下的docusaurus可执行文件。

• 解决步骤：
  先检查文件权限：

  ls -l /target_path/node_modules/.bin/docusaurus
  

  如果没有执行权限，添加权限：

  chmod +x /target_path/node_modules/.bin/docusaurus
  

  也可以先在本地Windows环境执行npm install，再挂载目录到容器，避免容器内安装依赖时的权限异常。

4. 挂载路径与项目根目录不匹配

确认本地D:\work\some_path是完整的Docusaurus项目根目录（必须包含package.json、docusaurus.config.js等核心文件），如果挂载的不是项目根目录，容器内/target_path下没有正确的项目结构，执行构建自然找不到Docusaurus命令。

• 解决：检查本地路径内容，确保是项目根目录后重新执行Docker挂载命令。

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