Jiwon Min Developer

解决在 Windows 11 上安装 Node.js 时的包安装错误

在 Windows 11 上安装 Node.js 时，你可能会遇到与附加软件包安装相关的错误。 这些错误通常是由于某些 Node.js 包需要使用 C/C++ 和 Python 进行编译而引起的。 本指南提供了详细的解决方案，以高效地解决这些问题并确保安装过程顺利。 一个常见的错误是使用 chocolaty 安装附加工具时产生的。 如果 visualstudio2019-workload-vctools 无法安装在现有的 chocolaty 路径中，可能会导致安装失败。 安装过程会显示一个 CMD 屏幕，并使用 PowerShell 进行安装。 尽管多次尝试，你可能会发现无法完成干净的安装。

node.js

© Pixabay © CopyrightFreePictures

为什么会出现这个错误

多数情况下问题不在 Node 本身，而在 编译原生插件的工具链。部分 npm 包在缺少预编译二进制时会通过 node-gyp 调用 C/C++、Python 工具。Windows 安装向导的“自动安装必要工具”会走 Chocolatey，并尝试安装 visualstudio2019-workload-vctools。

Chocolatey 状态损坏或 Build Tools 工作负载不匹配时，会反复出现类似信息：

visualstudio2019-workload-vctools not installed. the package was not found with the source(s) listed.

确认现象

在 Windows 11 上安装 Node.js 时，可能会出现与附加包安装相关的错误。 这些错误通常是由于某些 Node.js 包需要使用 C/C++ 和 Python 进行编译。 本文旨在记录如何高效解决这些问题，以帮助你顺利完成安装。

一个常见的错误发生在使用 chocolaty 安装附加工具时。 如果 visualstudio2019-workload-vctools 无法安装到现有的 chocolaty 路径，可能会导致安装失败。

visualstudio2019-workload-vctools not installed. the package was not found with the source(s) listed.

如果你在 Windows 11 上安装 Node.js 过程中遇到与附加包安装相关的上述错误消息，本文将提供解决方法。 本文旨在为初学者和经验丰富的开发者提供清晰可行的解决方案，以解决安装过程中常见的问题。

Automatically install

在 Node.js 安装过程中安装所需工具

在 Node.js 安装过程中，会出现一个如上图所示的选项，帮助你安装所需的附加工具。 通常情况下，勾选此项并继续，安装过程应该能够正常完成。

Necessary tools installing

正在安装所需工具

Installation failure

安装过程中出现错误

这时会显示一个 CMD 窗口，通过 PowerShell 来安装使用 Node.js 所需的附加工具。 如果在安装过程中出现如上图所示的错误，无论重试多少次，都无法完成干净的安装。

1. 重新安装 Chocolaty

  • 导航到 C:\ProgramData\chocolaty 目录并删除该目录。 重新安装 Node.js 时，chocolaty 和所需工具也会被重新安装。 Chocolatey folder

2. 安装 Visual Studio Build Tools

安装完成

Node.js 和所需软件包的安装现已全部完成！ 你的开发环境已经准备就绪。

以下是一些额外的验证步骤：

  1. 检查 Node.js 版本：
    要验证安装是否成功，请运行以下命令： 
    # 此命令可用于检查 Node.js 和 npm 的版本。
node -v
npm -v
  2. 创建一个基本项目：
    为了确认 Node.js 是否已正确安装，可以创建一个简单的项目。导航到你选择的目录并运行以下命令： 
    # 此命令将创建一个新的项目目录并初始化基本的包设置。
mkdir my-node-project
cd my-node-project
npm init -y
  3. 安装必要的软件包：
    尝试为你的项目安装一些基本的软件包。例如，要安装 Express，请运行以下命令： 
    # 此命令将安装 Express 包，你可以用它来构建服务器。
npm install express
  4. 其他配置：
    如果还有其他需要的配置或软件包，现在是安装它们的好时机。根据你项目的需求安装必要的软件包并完成环境设置。

现在，Node.js 和所需工具已在你的 Windows 11 系统上安装和配置完毕。你已经准备好开始开发了。祝你编码愉快！

Upgrade successful

安装完成

防复发检查清单

  1. 在 管理员 shell 中执行 Chocolatey / Build Tools 步骤
  2. 安装后用 node -v、npm -v 以及一个需要原生模块的包做冒烟测试
  3. 公司电脑需确认策略是否禁止安装 VS Build Tools
  4. 用 官方安装包 或版本管理器统一 Node LTS
  5. CI 优先使用已缓存 Build Tools 的镜像，或尽量避免原生编译

替代路径

  • 先单独安装 Visual Studio Build Tools，再重装 Node
  • 用 npm config set msvs_version 2019 对齐 node-gyp 年份
  • 若不需要 Windows 原生模块，可改用 WSL2 中的 Node

参考文献资料