NX CLI 安装问题 - 缺少 Linux 原生模块

问题现象

在使用 NX 构建 Angular 项目时，特别是在 GitHub Actions CI 环境中运行时，常见以下错误：

npm ERR! code 1
npm ERR! path /runner/_work/myapp/node_modules/nx
npm ERR! command failed npm ERR! command sh -c node ./bin/post-install
npm ERR! /runner/_work/myapp/node_modules/nx/src/native/index.js:244
npm ERR!     throw loadError
npm ERR!     ^
npm ERR!
npm ERR! Error: Cannot find module '@nx/nx-linux-x64-gnu'

NX 会显示明确的平台依赖缺失提示：

NX   Missing Platform Dependency
The Nx CLI could not find or load the native binary for your
supported platform (linux-x64). This likely means that optional
dependencies were not installed correctly, or your system is missing
some system dependencies.

此错误会导致构建过程失败，退出代码为 1。

根本原因

该问题通常由以下原因引起：

• 可选依赖未正确安装：NX CLI 依赖于平台特定的原生模块（如 @nx/nx-linux-x64-gnu）
• CI 环境限制：GitHub Actions 等环境在安装依赖时可能跳过可选依赖
• 缓存或锁定文件问题：package-lock.json 或 npm 缓存可能导致依赖解析错误

推荐解决方案

方案一：显式声明可选依赖（推荐）

步骤：

1. 在 package.json 中明确添加平台依赖（替换 18.0.4 为你的实际 NX 版本）：

{
  "dependencies": {
    // 其他依赖...
  },
  "optionalDependencies": {
    "@nx/nx-darwin-arm64": "18.0.4",
    "@nx/nx-darwin-x64": "18.0.4",
    "@nx/nx-linux-x64-gnu": "18.0.4",
    "@nx/nx-win32-x64-msvc": "18.0.4"
  }
}

2. 在 CI 脚本中使用 --include=optional 标志：

# GitHub Actions 示例
- name: 安装依赖
  run: npm ci --include=optional  # 或 npm install --include=optional

原理说明

NX 的本机二进制文件作为可选依赖发布：

• 默认安装时 npm 会忽略可选依赖
• --include=optional 强制安装可选依赖
• 声明具体版本确保安装正确的二进制模块

方案二：清除缓存与锁定文件

当方案一无效时可尝试此备选方案：

# 清理所有缓存和依赖
npm cache clean --force
rm -rf node_modules
rm package-lock.json

# 重新安装依赖
npm install

注意事项

此方法可能导致：

• 依赖版本意外更新
• 生产环境构建不一致 建议在 CI 脚本中添加清理步骤：

- name: 清理缓存
  run: npm cache clean --force
- name: 删除 node_modules
  run: rm -rf node_modules
- name: 删除锁定文件
  run: rm package-lock.json

补充建议

验证平台依赖

安装后检查是否正确包含平台模块：

ls node_modules/@nx/nx-* 
# 应出现类似：nx-linux-x64-gnu

处理缓存问题

如果遇到顽固性错误，完整清理缓存：

npm cache verify --force

NPM版本兼容性

不推荐降级方案

部分用户建议降级npm解决该问题，但这会带来：

npm install -g npm@6  # 不推荐

降级 npm 可能导致：

• 安全漏洞风险
• 与现代包不兼容
• 团队协作问题

总结

解决 Cannot find module '@nx/nx-linux-x64-gnu' 的核心是确保 NX 的平台依赖正确安装：

1. 首选方案：声明 optionalDependencies + --include=optional
2. 备选方案：彻底清理缓存和锁定文件后重装
3. 避免方案：npm 降级会导致长期维护问题

遵循这些方案后，NX 应能在 CI 环境中正确加载平台原生模块，解决构建失败问题。

官方参考文档：NX 安装问题排查指南