如何在 Windows 上安装和配置 Node.js 和 NPM

Node.js 是一个基于 Chrome V8 引擎构建的开源、跨平台 JavaScript 运行时，可在浏览器外执行 JavaScript 代码。NPM（Node Package Manager） 是与 Node.js 捆绑的默认包管理器，提供对超过两百万个可复用包的访问。两者共同构成了在 Windows 上构建服务器端应用程序、CLI 工具、REST API 和全栈 JavaScript 项目的基础工具链。

本指南涵盖了在 Windows 上安装、验证、配置 Node.js 和 NPM 以及首个应用程序的完整工作流程——包括版本管理、PATH 故障排除、全局与本地包作用域，以及大多数教程所忽略的生产级注意事项。

安装前选择正确的 Node.js 版本

Node.js 的发布计划遵循可预测的节奏，这直接影响您的选择：

LTS 版本采用偶数主版本号（如 20.x、22.x），并在 30 个月内接收关键安全补丁。Current 版本采用奇数主版本号，若满足稳定性标准，将在六个月后过渡为 LTS 状态。

对于大多数开发者和服务器部署——包括托管在 VPS 主机 上的应用程序——LTS 是正确的选择。Current 分支仅在您明确需要某个尚未进入活跃 LTS 版本线的 V8 特性或 Node.js API 时才适用。

NVM for Windows：直接安装的专业替代方案

在使用 MSI 安装程序之前，请考虑是否需要 nvm-for-windows（Windows 版 Node 版本管理器）。直接安装程序会将系统绑定到单一 Node.js 版本。NVM 允许您并排安装多个版本，并按项目切换——在维护旧代码库的同时兼顾现代项目时至关重要。

从其官方 GitHub 发布页面安装 nvm-for-windows，然后使用：

“`

nvm install 20.14.0

nvm use 20.14.0

nvm list

“`

如果您只管理单个项目或首次学习 Node.js，MSI 安装程序已足够。对于专业环境，强烈推荐使用 NVM。

第一步：下载 Node.js 安装程序

1. 访问官方 Node.js 网站 nodejs.org。
2. 选择 LTS 标签，并根据您的架构下载 Windows 安装程序（`.msi`）。几乎所有现代 Windows 机器均为 64 位（`node-v20.x.x-x64.msi`）。ARM64 版本适用于 Windows on ARM 设备。
3. 在执行安装程序之前，请对照 Node.js 下载页面上发布的值验证已下载文件的 SHA-256 校验和。在任何注重安全的环境中，此步骤不可省略。

在 PowerShell 中验证校验和：

“`powershell

Get-FileHash .node-v20.14.0-x64.msi -Algorithm SHA256

“`

将输出与已发布的哈希值进行比对。不匹配表示下载文件已损坏或被篡改。

第二步：安装 Node.js 和 NPM

1. 双击已下载的 `.msi` 文件以启动安装向导。
2. 在欢迎界面点击下一步。
3. 接受最终用户许可协议，然后点击下一步。
4. 默认安装路径为 `C:Program Filesnodejs`。除非您有特定原因需要更改（例如，为管理磁盘空间而使用非系统盘），否则保持默认即可。
5. 在自定义安装界面，确认已选中 npm package manager。默认情况下已启用。
6. 在本机模块工具界面，您将看到自动安装 Chocolatey、Python 和 Visual Studio Build Tools 的选项。如果您预计需要安装包含原生 C++ 插件的 NPM 包（例如 `bcrypt`、`sharp`、依赖 `node-gyp` 的包），请勾选此选项。此步骤将安装数 GB 的工具——如果您只需要纯 JavaScript 包，可跳过。
7. 点击安装，然后点击完成。

安装程序会自动将 `node.exe` 和 `npm.cmd` 注册到 `C:Program Filesnodejs` 下的系统 `PATH` 环境变量中。

安装程序对系统的实际影响

了解这些副作用可以避免日后的调试麻烦：

• 将 `C:Program Filesnodejs` 添加到系统 PATH（对所有用户可用）。
• 创建 `C:Users<username>AppDataRoamingnpm` 作为默认全局包前缀。
• 在 `HKLMSOFTWARENode.js` 下的 Windows 注册表中注册 Node.js。
• 将 `npx`（NPM 包运行器）与 `npm` 一同安装。

第三步：验证安装

打开一个新的命令提示符或 PowerShell 窗口。”新的”这一限定词很重要——现有终端会话会缓存旧的 PATH，不会反映安装程序所做的更改。

“`

node -v

“`

预期输出：`v20.14.0`（或您安装的版本）

“`

npm -v

“`

预期输出：`10.x.x`

“`

npx -v

“`

预期输出：与 npm 版本匹配或接近

如果 `node` 无法识别，说明 PATH 未正确更新。手动修复：

1. 打开系统属性 > 高级 > 环境变量。
2. 在系统变量下，找到 `Path` 并点击编辑。
3. 如果缺少 `C:Program Filesnodejs`，请添加。
4. 点击确定，关闭所有终端窗口，然后重新打开。

诊断常见的安装后问题

问题：`npm` 可以识别，但 `node` 无法识别（或反之）。

原因：PATH 条目不完整，或与 Chocolatey 或之前的 NVM 安装存在冲突。

解决方法：运行 `where node` 和 `where npm` 以确认正在解析哪些二进制文件。删除过时的条目。

问题：运行 `npm install -g` 时出现 `EACCES` 权限错误。

原因：全局前缀目录对当前用户缺少写入权限。

解决方法：将全局前缀更改为用户自有目录（见第五步）。

问题：`node` 打开了 Microsoft Store，而非运行 Node.js。

原因：Windows 10/11 为 `node` 内置了应用执行别名，会重定向到应用商店。

解决方法：前往设置 > 应用 > 应用执行别名，禁用 `python.exe` 和 `node.exe`（如存在）的别名。

第四步：将 NPM 更新至最新版本

Node.js 安装程序捆绑的 NPM 版本通常落后于当前版本一到两个次要版本。安装后请立即更新：

“`

npm install -g npm@latest

“`

`-g` 标志将包安装到全局前缀目录，使其在系统范围内可用。更新后重新验证：

“`

npm -v

“`

重要边缘情况：在 Windows 上，全局更新 NPM 有时会在 `C:Program Filesnodejs` 中留下指向旧版本的过时 `npm.cmd`，而新版本安装在 `C:Users<username>AppDataRoamingnpm` 中。如果更新后 `npm -v` 仍显示旧版本，请检查 PATH 中哪个二进制文件排在前面：

“`

where npm

“`

`AppDataRoamingnpm` 下的路径应在输出中出现在 `C:Program Filesnodejs` 之前。如果不是，请相应调整 PATH 条目的顺序。

第五步：为您的环境配置 NPM

NPM 的配置存储在 `.npmrc` 文件中，该文件可存在于三个级别：每个项目、每个用户（`C:Users<username>.npmrc`）和全局（`C:Program Filesnodejsnode_modulesnpmnpmrc`）。每个项目的设置会覆盖每个用户的设置，而每个用户的设置会覆盖全局设置。

更改全局包前缀

默认全局前缀（`AppDataRoamingnpm`）适用于大多数用户，但在共享服务器上或存在磁盘配额时，您可能需要重定向：

“`

npm config set prefix "D:NodeGlobal"

“`

更改前缀后，将新的 `bin` 子目录添加到 PATH：

“`

setx PATH "%PATH%;D:NodeGlobal"

“`

配置私有或镜像注册表

企业环境和隔离服务器通常使用私有 NPM 注册表（Verdaccio、Nexus、Artifactory）：

“`

npm config set registry "https://your-private-registry.example.com/"

“`

对私有注册表进行身份验证：

“`

npm login –registry=https://your-private-registry.example.com/

“`

对于仅限作用域的包（例如 `@mycompany/*`），您可以将该作用域单独路由到私有注册表，同时保持公共注册表不变：

“`

npm config set @mycompany:registry "https://your-private-registry.example.com/"

“`

配置 HTTP 代理

如果您的 Windows 机器位于企业代理之后：

“`

npm config set proxy "http://proxy.company.com:8080"

npm config set https-proxy "http://proxy.company.com:8080"

“`

查看所有当前设置

“`

npm config list

npm config list –json

“`

`–json` 标志输出机器可读的配置，适用于脚本编写和 CI/CD 管道诊断。

NPM 配置参考

第六步：创建并运行 Node.js 应用程序

初始化项目

“`

mkdir my-node-app

cd my-node-app

npm init -y

“`

`npm init -y` 会根据目录名称和您的 NPM 用户配置生成带有默认值的 `package.json`。`package.json` 文件是应用程序的清单——它定义了入口点、脚本、依赖项和元数据。

构建基本 HTTP 服务器

在项目目录中创建 `app.js`：

“`javascript

// app.js

const http = require('http');

const hostname = '127.0.0.1';

const port = 3000;

const server = http.createServer((req, res) => {

res.statusCode = 200;

res.setHeader('Content-Type', 'text/plain');

res.end('Hello, World!n');

});

server.listen(port, hostname, () => {

console.log(`Server running at http://${hostname}:${port}/`);

});

“`

运行：

“`

node app.js

“`

在浏览器中访问 `http://127.0.0.1:3000/`，您应该看到 `Hello, World!`。

技术说明：Node.js 使用由 libuv 支持的单线程事件循环处理 I/O 操作。`http.createServer` 回调在每个传入请求时触发，不会阻塞事件循环。这种架构使 Node.js 在 I/O 密集型工作负载中非常高效，但在没有工作线程或子进程的情况下不适合 CPU 密集型任务。

添加 Express 框架

Express 是 Node.js 的事实标准 HTTP 框架，提供路由、中间件支持和简洁的请求/响应抽象：

“`

npm install express

“`

这会将 Express 安装到本地（`node_modules/`），并将其作为依赖项记录在 `package.json` 中。更新 `app.js`：

“`javascript

const express = require('express');

const app = express();

const port = 3000;

app.get('/', (req, res) => {

res.send('Hello from Express!');

});

app.listen(port, () => {

console.log(`Server running at http://localhost:${port}`);

});

“`

“`

node app.js

“`

访问 `http://localhost:3000/` 以确认响应。

理解 `node_modules` 和 `.gitignore`

`node_modules` 目录可能包含数百 MB 的文件。切勿将其提交到版本控制。创建 `.gitignore` 文件：

“`

node_modules/

.env

“`

协作者和部署管道通过运行 `npm install` 来恢复依赖项，该命令读取 `package.json` 和 `package-lock.json` 以重现精确的依赖树。

第七步：管理包——本地与全局

理解本地和全局包安装之间的区别是 Node.js 新手最常见的困惑来源之一。

关键规则：如果一个包提供了您希望在任何地方都能使用的命令行工具（例如 `nodemon`、`eslint`、`typescript`），请全局安装。如果它是您的应用程序通过 `require()` 或 `import` 导入的库，请本地安装。

使用 PM2 在生产环境中运行应用程序

对于部署在服务器上的任何 Node.js 应用程序——无论是在 VPS 主机实例还是独立服务器上——直接运行 `node app.js` 是不够的。如果终端关闭或发生未处理的异常，进程将会终止。

PM2 是 Node.js 生产环境的标准进程管理器：

“`

npm install -g pm2

pm2 start app.js –name "my-app"

pm2 startup

pm2 save

“`

`pm2 startup` 生成一条命令，用于配置 PM2 在系统重启时自动重启您的应用程序。`pm2 save` 持久化当前进程列表。

第八步：安全加固与审计

运行依赖项审计

“`

npm audit

“`

NPM 将您已安装的包与 GitHub Advisory Database 进行交叉比对。任何已知漏洞都会以严重级别（低、中、高、严重）和修复路径的形式报告。

“`

npm audit fix

“`

这会自动将存在漏洞的包升级到最近的非破坏性已修补版本。对于破坏性更改，请查看输出并手动升级。

固定依赖项版本

在 `package.json` 中，NPM 默认使用语义版本范围（`^1.2.3` 允许次要版本和补丁更新）。在生产环境中，固定精确版本以防止供应链意外：

“`

npm config set save-exact true

“`

或者手动将 `^` 前缀替换为 `package.json` 中的精确版本字符串，并提交 `package-lock.json` 文件。

避免以管理员身份运行 NPM

以提升权限运行 `npm install -g` 会写入由 Administrator 账户拥有的文件，这可能导致后续非提升操作出现权限错误。配置用户自有的全局前缀（见第五步）可以完全消除对提升权限的需求。

将 Node.js 应用程序部署到服务器

本地开发只是第一阶段。生产部署引入了额外要求：进程管理、反向代理、TLS 终止和环境变量管理。

在 Linux VPS 主机实例上，典型的生产技术栈将 Node.js 与 Nginx 作为反向代理配合使用。Nginx 处理 TLS 终止（使用来自 SSL 证书等提供商的证书），并将请求转发到监听本地端口的 Node.js 进程。

对于偏好托管控制面板环境的团队，带 cPanel 的 VPS 通过 cPanel 界面提供 Node.js 应用程序管理，无需直接进行 SSH 配置即可简化部署。

特定于环境的配置（数据库凭据、API 密钥、端口号）绝不应硬编码。使用带有 `dotenv` 包的 `.env` 文件：

“`

npm install dotenv

“`

“`javascript

require('dotenv').config();

const port = process.env.PORT || 3000;

“`

决策矩阵：何时使用各种安装方法

关键技术要点

• 生产和团队环境始终安装 LTS 版本。仅在需要特定 V8 或 Node.js API 功能时才使用 Current 版本。
• 在需要多个 Node.js 版本共存的任何环境中使用 nvm-for-windows。
• 执行前验证安装程序的 SHA-256 校验和。
• 将全局 NPM 前缀更改为用户自有目录，以避免权限错误并消除对提升权限的需求。
• 切勿将 `node_modules/` 提交到版本控制。始终提交 `package-lock.json`。
• 在生产管道中，每次 `npm install` 后运行 `npm audit`。
• 在任何服务器部署中使用 PM2 进行进程管理——切勿在生产环境中直接运行 `node app.js`。
• 在反向代理层（Nginx、Caddy）终止 TLS，而非在 Node.js 进程内部，以获得更好的性能和证书管理。
• 将密钥存储在通过 `dotenv` 加载的环境变量中，切勿存储在源代码中。

常见问题解答

Windows 上 Node.js LTS 和 Current 有什么区别？

LTS 版本在 30 个月内接收安全和稳定性补丁，采用偶数主版本号（18、20、22）。Current 版本包含最新的语言和运行时特性，但仅支持六个月，之后过渡为 LTS 或被放弃。对于 Windows 生产部署，始终使用 LTS。

为什么 `npm install -g` 在 Windows 上出现权限错误？

默认全局前缀（`C:Users<username>AppDataRoamingnpm`）有时由于 UAC 策略或之前以管理员身份运行的安装而缺少写入权限。解决方法是以管理员身份运行终端（不建议长期使用），或使用 `npm config set prefix "C:yourpath"` 将全局前缀重新配置为您的用户账户拥有的目录。

我可以在 Windows 上同时运行多个 Node.js 版本吗？

可以，使用 nvm-for-windows。安装后，使用 `nvm install <version>` 和 `nvm use <version>` 切换活跃运行时。每个版本维护自己的全局包目录，防止跨版本冲突。

`package-lock.json` 是什么，我应该提交它吗？

`package-lock.json` 是在 `npm install` 期间解析的整个依赖树的精确、确定性记录。它确保每个开发者和每次 CI/CD 运行都安装相同的包版本。始终将其提交到版本控制，切勿手动编辑。

如何在没有服务器的情况下让 Node.js 应用程序在 Windows 启动时自动运行？

对于开发机器，使用 PM2 配合 `pm2 startup` 和 `pm2 save`。对于 Windows 服务集成，`node-windows` 等工具可将 Node.js 进程包装为原生 Windows 服务，支持通过服务 MMC 管理单元进行管理，并在故障或重启时自动重启。