使用npm workspace的Monorepo在GitHub Actions中ESLint依赖缺失问题

核心原因 #

GitHub Actions环境中，npm workspace的依赖安装逻辑和本地存在差异，主要涉及全局/局部依赖的调用路径问题，以及workspace下依赖的hoisting（提升）配置未正常生效。

具体解决步骤 #

1. 统一在根package.json声明公共工具依赖 #

将ESLint、eslint-plugin-react-hooks这类跨子包使用的工具依赖，放在根目录的package.json的devDependencies中，而非单独子包内。这样npm安装时会统一将依赖放到根node_modules，所有子包可共享调用。

示例根package.json片段：

{
  "name": "monorepo-root",
  "private": true,
  "workspaces": [
    "packages/*"
  ],
  "devDependencies": {
    "eslint": "^8.50.0",
    "eslint-plugin-react-hooks": "^4.6.0",
    // 其他公共开发依赖
  },
  "scripts": {
    "lint": "eslint ."
  }
}

2. 在GitHub Actions中用npm ci安装依赖 #

不要单独安装ESLint，直接执行npm ci替代npm install——npm ci会严格按照package-lock.json安装依赖，保证和本地环境完全一致，同时自动处理workspace的依赖提升逻辑。

示例工作流片段：

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20 # 与本地使用的Node版本保持一致
          cache: 'npm'
      - run: npm ci
      - run: npm run lint

3. 检查ESLint配置文件的插件引用 #

确保子包的ESLint配置（如.eslintrc.js）中，插件引用无需手动指定路径，直接使用插件名称即可：

module.exports = {
  extends: [
    'eslint:recommended',
    'plugin:react-hooks/recommended'
  ],
  plugins: ['react-hooks'],
  // 其他配置项
};

4. 兜底方案：禁用依赖扁平化（按需使用） #

若部分依赖因hoisting出现冲突，可在根package.json中添加配置关闭自动提升：

{
  "installConfig": {
    "hoist": false
  }
}

5. 确认依赖锁文件已提交 #

确保根目录的package-lock.json已提交至GitHub，npm ci需要该文件来精确还原依赖环境。

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