项目前端开发环境搭建

工具简介

Node.js

Node.js 是一个开源、跨平台的 JavaScript 运行时环境。它基于 Chrome 使用的 V8 引擎，使 JavaScript 可以在浏览器之外的 运行环境 中执行。

Node.js 不仅能用于开发 Web 服务端程序，还可用于构建前端工程化工具、命令行工具、自动化脚本等。现代前端项目通常依赖 Node.js 来运行构建工具、安装依赖和启动开发服务器。

V8 会使用即时编译等 编译技术 执行 JavaScript。相较于传统逐行解释的 脚本语言 执行方式，这类优化能够提升代码的 运行速度，并帮助团队降低重复搭建工具链带来的 开发成本。

npm

npm 是 Node.js 生态中常用的包管理器。安装 Node.js 时通常会同时安装 npm，因此一般不需要单独安装。

npm 既连接用于在线提供开源 Node.js 软件包的注册表，也提供命令行工具，用于完成以下工作：

• 根据 package.json 安装和管理项目依赖。
• 通过 package-lock.json 锁定依赖解析结果，提高不同环境中的安装一致性。
• 执行 package.json 中定义的脚本，例如 npm run dev。
• 发布和维护 npm 软件包。

Yarn、pnpm 和 cnpm 都与 npm 生态有关，但它们的定位并不完全相同。Yarn 和 pnpm 是可选的包管理器，cnpm 是兼容 npm 使用方式的客户端。它们不应被简单理解为“npm 的国内镜像”。一个项目应尽量统一包管理器，并提交对应的锁文件，避免混用后产生依赖差异。

NVM for Windows

NVM for Windows 是 Windows 平台上的 Node.js 版本管理工具，可在同一台计算机上安装和切换多个 Node.js 版本。

主要用途包括：

• 安装、卸载和查看不同版本的 Node.js。
• 根据项目要求切换 Node.js 版本。
• 设置当前生效的 Node.js 版本。
• 降低多个项目对不同 Node.js 版本的兼容成本。

注意：Windows 使用的是 NVM for Windows，它与 macOS、Linux 上常见的 nvm 不是同一个项目，安装方式和部分命令存在差异。

安装方案说明

推荐使用 NVM for Windows 统一安装和管理 Node.js，不建议先安装独立版 Node.js，再安装 NVM for Windows。两套安装同时存在时，可能因环境变量或安装目录冲突，导致 nvm use 切换后 node -v 仍显示旧版本。

本项目使用的 Node.js 版本为 22.17.0。课程截图中还演示了 14.20.0，该版本仅用于需要兼容旧项目时的版本切换练习，不应作为当前项目的默认版本。

清理旧环境

已经安装过 Node.js 或 NVM for Windows 时，建议先清理旧环境；全新电脑可跳过本节。

第一步：关闭相关程序

关闭正在使用 Node.js 的终端、IDE、开发服务器和其他相关进程，避免文件被占用。

第二步：记录当前环境

打开命令提示符，执行以下命令：

node -v
npm -v
where node
where npm

where 命令可以帮助确认系统实际调用的是哪个目录中的可执行文件。

第三步：卸载旧版 Node.js

在 Windows 的“设置”或“控制面板”中卸载独立安装的 Node.js，然后检查原安装目录是否仍有残留。

如果后续准备使用 NVM for Windows，尤其要确认原来的 Node.js 实体目录没有占用 NVM 的符号链接位置。删除目录前应先确认其中没有需要保留的配置或文件。

第四步：卸载旧版 NVM for Windows

需要重新安装 NVM for Windows 时，可通过 Windows 的应用卸载功能进行卸载。卸载后检查 NVM_HOME、NVM_SYMLINK 和 PATH 中是否仍保留失效配置。

不要直接删除不熟悉的环境变量。应先确认变量指向旧的 NVM 安装目录，再进行清理。

第五步：处理 npm 残留

可先使用以下命令查看 npm 的缓存和全局安装目录：

npm config get cache
npm config get prefix

确认不再需要旧环境后，再清理对应目录。用户目录中的 .npmrc 可能包含镜像、代理或私有仓库配置，删除前应先备份。

安装 NVM for Windows

第一步：运行安装程序

运行团队或课程提供的 NVM for Windows 安装程序。安装过程中建议使用默认目录；修改目录时，应避免路径包含特殊字符，并确保符号链接目录不存在同名实体文件夹。

如果安装程序询问是否接管已有 Node.js，推荐先退出安装，按照前文卸载独立版 Node.js 后再重新安装，避免路径冲突。

第二步：重新打开终端

安装完成后，关闭并重新打开命令提示符或 PowerShell。切换 Node.js 版本时，Windows 通常需要管理员权限，因此建议以管理员身份打开终端。

执行以下命令验证 NVM for Windows：

nvm version

部分旧版本也支持：

nvm -v

安装和切换 Node.js 版本

安装当前项目版本

执行以下命令安装本项目要求的 Node.js：

nvm install 22.17.0

安装完成后切换到该版本：

nvm use 22.17.0

切换时若 Windows 弹出权限确认窗口，应在确认命令来源无误后允许操作。

验证当前版本

执行以下命令：

nvm current
node -v
npm -v

也可以查看本机已安装的全部 Node.js 版本：

nvm list

旧版本的 NVM for Windows 也可使用：

nvm ls

列表中带星号的版本是当前生效版本。

旧项目版本切换示例

仅当旧项目明确要求 Node.js 14.20.0 时，再安装该版本：

nvm install 14.20.0

安装后可切换并查看版本：

nvm use 14.20.0
nvm list

旧项目处理完成后，应切回当前项目版本：

nvm use 22.17.0

启动前端项目

第一步：进入项目目录

打开命令提示符或 IDE 终端，进入项目的 webui 目录：

cd <项目目录>\webui

第二步：确认 Node.js 版本

node -v
npm -v

当前项目应使用 Node.js 22.17.0。如果版本不正确，执行：

nvm use 22.17.0

第三步：安装项目依赖

首次运行项目或依赖发生变化时，需要先安装依赖。

项目已提交且未修改 package-lock.json 时，可优先使用可重复安装命令：

npm ci

没有 package-lock.json，或需要更新锁文件时，使用：

npm install

不要在同一项目中随意混用 npm、Yarn 和 pnpm，否则可能同时生成多个锁文件并造成依赖版本不一致。

第四步：启动开发服务器

npm run dev

启动成功后，应以终端输出的地址为准。Vite 项目的默认地址通常为：

http://localhost:5173

如果 5173 端口已被占用，开发服务器可能自动选择其他端口，因此不要只根据固定地址判断是否启动成功。

常见问题排查

nvm use 执行成功，但 Node.js 版本没有变化

依次检查以下项目：

• 以管理员身份重新打开终端。
• 关闭旧终端窗口后再重新验证。
• 执行 where node，检查是否存在独立版 Node.js 的路径冲突。
• 执行 nvm debug，查看 NVM for Windows 检测到的问题。
• 确认 NVM 的符号链接目录没有被同名实体目录占用。

提示找不到 node 或 npm

先执行：

nvm list
nvm use 22.17.0

然后关闭并重新打开终端。如果仍然失败，应检查 NVM_HOME、NVM_SYMLINK 和 PATH。

npm install 或 npm ci 失败

重点检查：

• 当前 Node.js 版本是否满足项目要求。
• package.json 与 package-lock.json 是否一致。
• 是否在正确的 webui 目录中执行命令。
• 网络、代理、镜像和私有仓库认证配置是否有效。
• 是否混用了不同包管理器生成的锁文件。

npm run dev 提示脚本不存在

打开 package.json，确认 scripts 中是否定义了 dev。npm run dev 只是执行项目声明的脚本，并不是所有前端项目都固定使用这一命令。