前端环境搭建

前端运行环境和工具

1、Node.js 是一个开源跨平台的 JavaScript 运行时环境，可以理解成 Java 中的 JDK；

官网：https://nodejs.org/ (opens new window)

2、npm 是 JavaScript 依赖包管理工具，可以进行前端项目的打包、依赖下载等，可以理解成 Java 中的 Maven；

官网：https://www.npmjs.com/ (opens new window)

3、Vite 是快速构建前端 Vue 项目的脚手架，可以理解为开发 Spring Boot 的 Spring Initializr 快速构建工具；

官网：https://cn.vitejs.dev/ (opens new window)

相较于后端，如表格所示：

前端 Vue	后端 Java
Node.js	JDK
npm	Maven
Vite	Spring Initializr

安装 Node.js

下载：Node.js 官方网站 (opens new window)

安装：下载 zip 压缩包，解压到指定目录即完成安装（免安装版，无需运行安装程序）。

Node.js 环境变量配置（目录自定义，以下以 D:\software\node-v20.12.0-win-x64 为例）

1、在 Node.js 安装目录 D:\software\node-v20.12.0-win-x64 下创建 2 个文件夹：

• node_global（全局依赖库目录，用于存放通过 npm install -g 安装的全局包）

• node_cache（缓存目录，用于存放 npm 下载的缓存文件）

2、在 D:\software\node-v20.12.0-win-x64 目录下 cmd 进入命令行窗口，执行：

npm config set prefix "D:\software\node-v20.12.0-win-x64\node_global"

npm config set cache "D:\software\node-v20.12.0-win-x64\node_cache"

3、查看有没有设置成功：

npm config get prefix

npm config get cache

4、配置环境变量 Path，在 Path 变量中添加如下路径：

D:\software\node-v20.12.0-win-x64 

D:\software\node-v20.12.0-win-x64\node_global

说明：

• 第一个路径是 Node.js 本身的安装目录，让系统找到 node 和 npm 命令
• 第二个路径是全局依赖库目录，让系统找到通过 npm install -g 安装的工具命令（如 pnpm、yarn 等）

在任意目录打开命令行窗口查看是否配置成功：

node -v

npm -v 

⚠️注：Node.js 已经自带 npm，安装 Node.js 时即已安装了 npm，故不需要再单独安装 npm；

nvm

nvm（Node Version Manager）是一个用于管理多个 Node.js 版本的工具。它允许你在同一台机器上轻松安装、管理和切换不同的 Node.js 版本，这对于需要在不同项目中使用不同版本 Node.js 的开发者来说非常有用。

nvm 的主要功能

• 安装多个 Node.js 版本：你可以安装多个版本的 Node.js，并根据需要进行切换。
• 设置默认 Node.js 版本：可以指定一个默认使用的 Node.js 版本。
• 按项目设置 Node.js 版本：每个项目目录下可以通过 .nvmrc 文件指定该项目所需的 Node.js 版本。
• 自动切换 Node.js 版本：当进入包含 .nvmrc 文件的项目目录时，nvm 可以自动切换到该文件中指定的 Node.js 版本。

安装 nvm

可参考网上教程：nvm安装详细教程（安装nvm、node、npm、cnpm、yarn及环境变量配置）-CSDN博客 (opens new window)

在 macOS 和 Linux 上安装 nvm

注意：macOS/Linux 上的 nvm 和 Windows 上的 nvm-windows 是两个不同的项目，由不同的作者维护，安装方式也不同。

1. 通过脚本安装：

   • 打开终端并运行以下命令来安装最新版本的 nvm：

     curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.5/install.sh | bash
     

   或者使用 wget：

   wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.5/install.sh | bash
   

2. 加载 nvm：

   • 安装完成后，关闭并重新打开你的终端，或者手动加载 nvm 到当前 shell 会话中：

     export NVM_DIR="$([ -z "${XDG_CONFIG_HOME-}" ] && printf %s "${HOME}/.nvm" || printf %s "${XDG_CONFIG_HOME}/nvm")"
     [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
     

3. 验证安装：

   • 确认 nvm 是否正确安装：

     command -v nvm
     

在 Windows 上安装 nvm-windows

对于 Windows 用户，推荐使用 nvm-windows，它是专门为 Windows 设计的 Node.js 版本管理器（与 macOS/Linux 的 nvm 是不同项目）。

1. 下载和安装：
   • 访问 nvm-windows GitHub Releases (opens new window) 页面下载最新的安装包。
   • 按照安装向导完成安装。
2. 使用 nvm-windows：
   • 安装后，你可以在命令提示符或 PowerShell 中使用 nvm 命令来管理 Node.js 版本。
3. 环境变量说明：
   • 安装过程中会自动配置以下环境变量：
     • NVM_HOME：nvm 的安装目录（存放各版本 Node.js）
     • NVM_SYMLINK：Node.js 的符号链接（快捷方式）目录，切换版本时会被更新指向当前使用的版本

nvm-windows 的符号链接机制（重要）

nvm-windows 通过**符号链接（快捷方式）**来实现版本切换，这是它的核心原理：

1. 安装多个版本时：每个 Node.js 版本会被安装到 NVM_HOME 下的独立目录中，例如：

   C:\nvm\nodejs\v20.12.0\   ← Node.js 20.12.0 的实际安装目录
   C:\nvm\nodejs\v18.20.0\   ← Node.js 18.20.0 的实际安装目录
   

2. NVM_SYMLINK 指向的目录是一个快捷方式：通常配置为 C:\Program Files\nodejs 或自定义路径，这个目录不是真实的文件夹，而是一个符号链接（快捷方式），指向当前正在使用的 Node.js 版本目录。

3. 执行 nvm use 20.12.0 时：nvm 会把符号链接重新指向 C:\nvm\nodejs\v20.12.0\，这样系统 PATH 中通过符号链接找到的 node 和 npm 命令就自动切换到了 20.12.0 版本。

4. 执行 nvm use 18.20.0 时：符号链接被重新指向 C:\nvm\nodejs\v18.20.0\，版本切换完成。

系统 PATH → NVM_SYMLINK 目录（快捷方式）→ 当前使用的 Node.js 版本目录

为什么用符号链接？

• 系统 PATH 只需配置一次（指向固定的符号链接路径），不需要每次切换版本都修改环境变量
• 切换版本时只改变符号链接的指向，速度快且不会污染系统环境变量
• 全局安装的包（npm install -g）会安装到当前版本对应的 node_global 目录中，各版本之间相互隔离

⚠️注意：

• 符号链接目录（如 C:\Program Files\nodejs）不要手动删除或修改，否则 nvm 切换会失效
• 如果切换版本后 node -v 没变化，以管理员身份重新打开命令行窗口再试（创建符号链接需要管理员权限）
• 配置 node_global 和 node_cache 时，路径建议用各版本目录下的路径，这样切换版本后全局包是隔离的；如果希望全局包跨版本共享，可以配置到一个统一的固定路径

常用命令

• 参考：nvm使用小结 | 沉梦听雨的编程指南 (opens new window)

⚠️注意事项：

• 后续通过 npm install -g 安装的 pnpm 和 yarn，可以在对应 Node.js 版本的 node_global 目录下找到
• 使用 nvm 管理时，每个版本的 Node.js 都会在 nvm 目录下有对应的版本文件夹，每个版本都有各自独立的 node_global 和 node_cache 目录（切换版本后全局包不共享）

安装 Yarn

1. 使用 npm 安装

   • 你可以直接通过 npm 来全局安装 Yarn：

     npm install --global yarn
     

2. 验证安装

   • 同样在命令行中输入以下命令来验证 Yarn 是否安装成功：

     yarn --version
     

安装 pnpm

1. 使用 npm 安装

   • 类似于 Yarn，你可以通过 npm 全局安装 pnpm：

     npm install -g pnpm
     

2. 验证安装

   • 使用以下命令确认 pnpm 已经正确安装：

     pnpm --version
     

Corepack 与 packageManager 字段

什么是 Corepack

Corepack 是 Node.js 官方内置的包管理器版本管理工具（Node 16.10+ 自带），用于解决"不同项目需要不同 pnpm/yarn 版本"的问题。可以理解为包管理器的 nvm。

• 启用：corepack enable
• 检查是否可用：corepack --version

packageManager 字段的作用

在项目的 package.json 中添加 packageManager 字段，可以锁定该项目使用的包管理器及版本：

{
  "packageManager": "pnpm@10.34.5"
}

工作原理

当 Corepack 启用后，运行 pnpm install 时：

1. Corepack 拦截 pnpm 命令
2. 读取 package.json 中的 packageManager 字段
3. 自动下载并使用指定的 pnpm@10.34.5 版本执行命令

即使你本地全局安装的 pnpm 是其他版本，Corepack 也会自动使用 packageManager 字段指定的版本，确保所有协作者使用同一个 pnpm 版本，避免因版本差异导致 pnpm-lock.yaml 不一致。

如果没有启用 Corepack

packageManager 字段不会生效，系统直接使用全局安装的 pnpm 版本。此时该字段仅作为版本声明，没有强制力。

常见提示说明

执行 pnpm install 时可能看到类似提示：

╭──────────────────────────────────────────╮
│   Update available! 10.34.5 → 11.20.0.   │
│   Changelog: https://pnpm.io/v/11.20.0   │
│     To update, run: pnpm add -g pnpm     │
╰──────────────────────────────────────────╯

这是 Corepack 下载的指定版本 pnpm 自身检测到有新版本发布的通知，不影响功能，可以忽略。项目已通过 packageManager 锁定版本，保持一致更稳妥，不建议随意升级。

总结

场景	行为
启用 Corepack + 有 packageManager 字段	自动使用指定版本，忽略全局版本
启用 Corepack + 无 packageManager 字段	使用 Corepack 默认版本
未启用 Corepack	packageManager 字段不生效，使用全局安装的版本

设置镜像源

淘宝 NPM 镜像现在已经迁移至 npmmirror，旧的淘宝镜像域名已经停止服务。新的镜像地址如下：

• 新的镜像站地址：https://npmmirror.com/
• 新的注册表地址：https://registry.npmmirror.com/

设置使用 npmmirror

要将你的 npm 配置为使用 npmmirror 作为默认源，你可以按照以下步骤操作：

# npm 设置镜像源
npm config set registry https://registry.npmmirror.com
# yarn 设置镜像源
yarn config set registry https://registry.npmmirror.com
# pnpm 设置镜像源
pnpm config set registry https://registry.npmmirror.com

# 验证设置是否成功
npm config get registry
yarn config get registry
pnpm config get registry

如果返回的是 https://registry.npmmirror.com，则表示你已经成功配置了使用 npmmirror。

# 如果需要切换回官方 npm 源，可以使用如下命令：
npm config set registry https://registry.npmjs.org/

注意事项

• 权限问题：如果你遇到权限错误（特别是在 macOS 或 Linux 上），可以尝试添加 sudo 前缀（例如 sudo npm install -g pnpm），或者考虑使用 nvm (Node Version Manager) 来管理 Node.js 环境，它可以在不需要管理员权限的情况下安装和更新 Node.js 及其包管理器。

• 环境变量：确保 Node.js、Yarn 和 pnpm 的安装路径已经被添加到系统的 PATH 环境变量中。这通常是在安装过程中自动完成的，但如果你手动安装了这些工具，则可能需要自己添加。

• 版本管理：对于不同的项目可能需要不同版本的 Node.js 和依赖库，推荐使用 nvm (Node Version Manager) 或者 fnm (Fast Node Manager) 来管理和切换 Node.js 版本。对于包管理器（pnpm/yarn）的版本管理，推荐使用 Node.js 内置的 Corepack（见上文）。

• 代理设置：如果你在中国或其他网络受限的地区，可能会发现从官方源下载非常慢。这时可以考虑配置镜像源，例如 npmmirror 镜像，来加速下载速度。