GitHub Actions Ubuntu环境下node_modules缺失致mocha命令找不到

核心原因 #

你遇到的问题本质是GitHub Actions的ubuntu-20.04主机环境中没有安装项目依赖——本地docker-compose运行时，依赖是在容器内部通过Dockerfile的RUN npm install安装的，但直接在Action主机执行测试脚本时，主机目录下没有node_modules，自然找不到mocha可执行文件。

具体解决方法 #

方法1：在Action主机环境先安装依赖 #

如果你的测试脚本是直接在Action主机运行（而非Docker容器内），需要先完成依赖安装步骤：

1. 在GitHub Actions工作流中添加Node.js环境配置和依赖安装步骤：

jobs:
  test:
    runs-on: ubuntu-20.04
    steps:
      - uses: actions/checkout@v4
      # 配置Node.js环境，版本和你的项目保持一致
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '18' # 替换为你的项目Node.js版本
          cache: 'npm' # 开启npm缓存，加速依赖安装
      # 安装项目依赖，推荐用npm ci确保和lock文件版本一致
      - name: Install dependencies
        run: npm ci
      # 执行测试脚本
      - name: Run tests
        run: npm run test-jobs-once-docker

2. 确认你的package.json中，test-jobs-once-docker脚本是直接调用本地node_modules里的mocha（而非全局mocha），比如：

"scripts": {
  "test-jobs-once-docker": "mocha ./test/**/*.test.js"
}

npm会自动从本地node_modules/.bin中查找mocha，无需全局安装。

方法2：在Docker容器内执行测试（更贴合本地运行逻辑） #

如果你的测试依赖Docker容器内的环境（比如需要和其他服务联动），应该直接在容器中执行测试，而非主机环境：

1. 恢复docker-compose.yml中web服务的基础配置（无需指定command，或者保持默认启动命令）。
2. 在GitHub Actions工作流中，用docker-compose run命令在容器内执行测试脚本：

jobs:
  test:
    runs-on: ubuntu-20.04
    steps:
      - uses: actions/checkout@v4
      # 启动依赖服务（如果有的话）
      - name: Start dependent services
        run: docker-compose up -d db redis # 替换为你的依赖服务名
      # 在web容器内执行测试
      - name: Run tests in Docker container
        run: docker-compose run webapp npm run test-jobs-once-docker
      # 测试完成后停止服务
      - name: Stop services
        run: docker-compose down

这种方式下，容器内已经通过Dockerfile的RUN npm install安装了依赖，所以能正常找到mocha。

方法3：用npx临时调用mocha（应急方案） #

如果不想安装完整依赖，可以修改package.json中的测试脚本，用npx临时下载并执行mocha：

"scripts": {
  "test-jobs-once-docker": "npx mocha ./test/**/*.test.js"
}

但这种方式每次执行都会重新下载mocha，速度较慢，不推荐长期使用。

关键注意点 #

• 优先选择方法2，和本地运行逻辑一致，避免环境差异
• 用npm ci代替npm install，确保依赖版本和本地完全一致，减少环境问题
• 确认Dockerfile中包含COPY package*.json ./和RUN npm install步骤，保证容器内有完整依赖

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