开发环境安装：Node.js 与工具链

第 1 章 · 开发环境安装：Node.js 与工具链

本章目标：在 Windows（主）/ macOS 上完成现代前端框架开发的全套工具链安装；能用 node -v、npm -v、git --version 自检；配置国内 npm 镜像；了解 nvm / fnm 多版本管理（可选）；安装 pnpm 与 Git；在小紫 AI 工作台或 VS Code 中打开终端、创建项目工作区；安装推荐扩展；能独立排查 PATH 环境变量与常见安装错误。

学时建议：2～3 小时（含 30 分钟跟练与排错）

前置：完成 frontend-web 模块 ch01～ch18（了解浏览器与 Node 运行时差异）；会使用文件资源管理器；具备基础命令行概念。

痛点说明：很多同学卡在「Node 装不上」「npm 一直超时」「node 不是内部命令」——本章用逐步截图级文字把环境搭通，不再靠复制一段命令碰运气。

1.1 为什么前端框架必须先装 Node.js

阶段	没有 Node	装好 Node + 工具链
写页面	手写 HTML/CSS/JS，浏览器直接打开	同上，仍可
用 Vue/React	无法使用脚手架、无法 `npm install`	`npm create vite` 一键建项目
本地开发	改代码需手动刷新	Vite 热更新（HMR）
联调贤紫 API	跨域难处理	dev server 配置 proxy
上线构建	无压缩、无 Tree Shaking	`npm run build` 产出 `dist`

学习路径（frontend-framework）
  ch01 装环境  →  ch02 搭脚手架  →  ch03 起学 Vue 语法
       ↑ 你在这里

说明：本地开发时前端常跑在 http://localhost:5173，通过 Vite 代理访问练习用后端 API（如 http://localhost:8000/api/v1），与具体公司业务无关。

1.2 下载并安装 Node.js LTS（Windows）

LTS（Long Term Support）= 长期支持版，稳定、文档多，学院与线上一致推荐 Node.js 20.x LTS（若官网已更新至 22 LTS，选带 LTS 标签的最高稳定版即可）。

1.2.1 逐步操作（Windows 10/11）

步骤	操作	说明
1	打开浏览器访问 https://nodejs.org/zh-cn	选中文站，避免下错架构
2	点击绿色按钮「推荐大多数用户使用」（LTS）	不要选 Current，除非老师明确要求
3	下载 `node-v20.x.x-x64.msi`（64 位系统）	ARM 笔记本选 arm64
4	双击 `.msi`，Next → 接受协议	全程默认即可
5	安装页勾选「Automatically install the necessary tools」（可选）	会提示装 Python/VS Build Tools，纯前端可跳过
6	保持默认安装路径 `C:\Program Files\nodejs\`	路径勿含中文与空格
7	勾选「Add to PATH」（一般默认已勾）	见 1.8 节排错
8	Install → Finish	安装完成

1.2.2 验证安装

必须新开一个终端（旧窗口读不到新 PATH）：

# Windows PowerShell 或 CMD
node -v
npm -v

期望输出示例（版本号因下载时间略有不同，大版本应为 20 或当前 LTS）：

v20.18.0
10.8.2

命令	含义	通过标准
`node -v`	Node 运行时版本	以 `v` 开头，如 `v20.x.x`
`npm -v`	npm 包管理器版本	纯数字，如 `10.x.x`
`node -e "console.log('ok')"`	快速跑一行 JS	终端打印 `ok`

1.2.3 macOS 安装（附）

方式	步骤	适合人群
官网 pkg	同 Windows，下载 `.pkg` 安装	新手首选
Homebrew	`brew install node@20`	已用 brew 的开发者
fnm	见 1.4 节	需多版本切换

# macOS 终端验证
node -v
npm -v
which node    # 应指向 /usr/local/bin/node 或 ~/.fnm/...

1.3 配置国内 npm 镜像（必做）

默认 registry 在国外，国内易出现 ETIMEDOUT、ECONNRESET。学院统一使用 npmmirror（原淘宝镜像）：

npm config set registry https://registry.npmmirror.com

验证是否生效：

npm config get registry
# 期望：https://registry.npmmirror.com/

场景	命令
单次安装走镜像	`npm install lodash --registry=https://registry.npmmirror.com`
恢复官方源	`npm config set registry https://registry.npmjs.org`
查看全部配置	`npm config list`

pnpm / yarn 镜像（可选，装完对应工具后执行）：

pnpm config set registry https://registry.npmmirror.com
yarn config set registry https://registry.npmmirror.com

1.4 多版本管理（可选）：nvm-windows / fnm

不同项目可能要求 Node 16 / 18 / 20，多版本管理器可在本机并存、一键切换。

1.4.1 Windows：nvm-windows

注意：与「nvm」Mac 版不是同一个项目，Windows 请搜 nvm-windows。

步骤	操作
1	若已装官方 Node，建议先卸载（避免 PATH 冲突）
2	下载 nvm-windows Releases 的 `nvm-setup.exe`
3	安装后新开 PowerShell

nvm version
nvm install 20.18.0
nvm use 20.18.0
node -v

1.4.2 macOS / Linux：fnm（推荐）

# 安装 fnm（官网脚本，以 fnm 文档为准）
curl -fsSL https://fnm.vercel.app/install | bash
fnm install 20
fnm use 20
node -v

工具	平台	特点
nvm-windows	Windows	学院 Windows 学员常用
fnm	全平台	速度快、跨平台一致
不装	任意	只学一门课、单一 LTS 足够

1.5 安装 pnpm 与对比 npm

pnpm 用硬链接节省磁盘，依赖隔离更严，贤紫部分 monorepo 子项目已采用。

# 方式一：npm 全局安装（最简单）
npm install -g pnpm

# 方式二：官方脚本（Windows PowerShell 需管理员或按官网说明）
# 见 https://pnpm.io/zh/installation

pnpm -v

维度	npm	pnpm
来源	Node 自带	需单独安装
锁文件	`package-lock.json`	`pnpm-lock.yaml`
`node_modules`	扁平、体积大	内容寻址、省空间
学院默认	ch02 以 npm 为主	可自选，命令几乎对应

# 命令对照
npm install          →  pnpm install
npm run dev          →  pnpm run dev
npx vite             →  pnpm exec vite  或  pnpm dlx vite

本章跟练统一用 npm；熟悉后可在 ch02 项目里改用 pnpm install。

1.6 安装 Git 与验证

框架脚手架、依赖安装、日后部署都依赖 Git（部分包从 GitHub 拉取）。

Windows

访问 https://git-scm.com/download/win 下载安装包
安装时推荐：Git from the command line and also from 3rd-party software（加入 PATH）
换行符选 Checkout as-is, commit Unix-style line endings（与 Linux CI 一致）

git --version
# 期望：git version 2.43.0.windows.1（2.4x 均可）

macOS

# 已装 Xcode Command Line Tools 则自带 git
git --version
# 若无：xcode-select --install  或  brew install git

首次使用 Git 建议配置	命令
用户名	`git config --global user.name "你的姓名"`
邮箱	`git config --global user.email "you@example.com"`