跳转到内容
AI 编程实战课

2.2 Node.js 与 pnpm 安装指南

📌 基于 Node.js LTS 版 · 2026-09 更新。Node 的版本号每半年跳一次，本节所有步骤只认官网上标着 LTS 的那个按钮，不认具体数字，所以即使版本号和截图对不上也不影响操作。

一、本节你会做出什么

你的电脑将具备本地运行网页项目的能力，并且你会亲手在 http://localhost:3000 打开一个真正跑在自己电脑上的网页。

📷 效果位：终端左边显示 node -v / pnpm -v 的输出，右边浏览器打开 localhost:3000

1.3 里说过，“跑起来”分本地运行和线上部署两种。第 1 章你做到了线上部署，今天补上本地运行这一半。装完这一套，从第 4 章起的所有项目才有地方落地。

二、开始前你需要

  • 已完成 2.1 认识终端，会 cd、ls、Ctrl + C
  • 一台能上网的电脑，预留 2GB 磁盘空间
  • 20 分钟不被打断的时间（装到一半去开会，回来容易忘了走到哪一步）

三、跟着做

第 1 步：先搞懂你在装什么（2 分钟，别跳）

装环境最难受的是“不知道自己在干嘛”。三句话讲清：

你要装的 一句话类比 没有它会怎样
Node.js 让 JavaScript 能脱离浏览器、直接在你电脑上运行的发动机 项目根本启动不了
npm（跟 Node 一起装，不用单独装） 装在发动机上的应用商店 装不了别人写好的现成功能
pnpm 同一个应用商店的更快、更省空间的版本 能用 npm 代替，但会更慢更占地方

再具体一点：你的项目会用到几百个别人写好的零件（登录、日历、图表……），这些零件叫包（package）。pnpm 就是帮你把这些包下载下来、管好版本的工具。项目里那个 package.json 文件，就是这个项目的零件清单。

为什么不直接用 npm？ npm 完全够用，本课选 pnpm 是因为它安装更快、多个项目共用同一份零件不重复占硬盘。如果你后面看到教程里写 npm install，把 npm 换成 pnpm 基本都通用。

第 2 步：装 Node.js

🍎 Mac

  1. 打开 nodejs.org
  2. 首页有两个大按钮，点标着 LTS 的那个（LTS = 长期支持版 = 稳定版。另一个 Current 是尝鲜版，不要装）
  3. 下载到一个 .pkg 文件，双击，一路「继续 → 同意 → 安装」，中途会让你输开机密码
  4. 安装完成后，关掉终端窗口，重新开一个（这一步很多人漏掉，导致后面验证失败）

📷 截图位 1：nodejs.org 首页，LTS 按钮高亮

🪟 Windows

  1. 打开 nodejs.org，同样点 LTS 那个按钮，下载 .msi 文件
  2. 双击运行，一路 Next
  3. 有一个勾必须留意：安装过程中有个 Add to PATH 的选项，默认是勾上的，别取消。它的作用是让终端在任何位置都能找到 node
  4. 中间可能出现一个「Tools for Native Modules」的勾选页，不用勾，直接 Next
  5. 装完后，关掉 PowerShell 窗口重新开一个

📷 截图位 2：Windows 安装器里 Add to PATH 选项

验证（Mac / Windows 通用）

在新开的终端里执行：

终端窗口
node -v
npm -v

看到两行版本号就成功了，类似：

v24.8.0
10.9.2

数字和你看到的不一样完全正常，只要打印出了版本号就是成功。反过来，如果看到 command not found 或 不是内部或外部命令，去本节第五部分找对应的解法。

第 3 步：装 pnpm

终端窗口
npm install -g pnpm

-g 表示 global（全局安装），意思是装到电脑上而不是装到某个项目里。这条命令会跑十几秒，屏幕上会滚一堆字，最后停下来就是好了。

验证：

终端窗口
pnpm -v

打印出版本号（比如 10.x.x）就成功了。

🪟 Windows 用户注意：如果这里报错 无法加载文件 ... 因为在此系统上禁止运行脚本，这是 PowerShell 的安全策略挡住了，不是你装错了。看第五部分的解法，两分钟能解决。

第 4 步：国内网络优化（在国内的同学建议做）

包是从国外服务器下载的，直连经常慢或者卡住。换成国内镜像源：

终端窗口
pnpm config set registry https://registry.npmmirror.com
npm config set registry https://registry.npmmirror.com

验证：

终端窗口
pnpm config get registry

打印出 https://registry.npmmirror.com/ 就生效了。

这一步随时可以撤销：把地址换回 https://registry.npmjs.org 即可。如果你后面遇到“某个包下载不下来”，可以试着切回官方源再装一次。

第 5 步：冒烟测试——跑起你的第一个本地网页

装完必须验一次，否则你不知道是真装好了还是埋了雷。

终端窗口
cd ~/Documents/ai-course        # Mac，换成你自己的路径
cd D:\ai-course                 # Windows，换成你自己的路径


pnpm create next-app@latest hello-node

它会问你一串问题。除了下面这一条，其余全部按回车用默认值：

问题 你的选择
Would you like to use TypeScript? 回车（默认 Yes）
Would you like to use Tailwind CSS? 回车（默认 Yes）
Would you like to use App Router? 回车（默认 Yes）
其余各项 一律回车

这些选项是什么意思，第 4 章会讲。现在你只需要知道：默认值就是本课全程使用的配置。

然后等它下载完（第一次会久一点，1~3 分钟），执行：

终端窗口
cd hello-node
pnpm dev

终端里会出现类似这样几行：

▲ Next.js 15.x
- Local:  http://localhost:3000
✓ Ready in 1.8s

注意：终端现在停住不动了，光标也不闪了——这是正常的，说明服务正在运行中。 这个窗口就别动了。

打开浏览器访问 http://localhost:3000，你会看到一个 Next.js 的欢迎页面。

📷 截图位 3：终端显示 Ready + 浏览器打开 localhost:3000

这个页面只有你自己能看到（还记得 1.3 那张对比表吗）。想停掉它：回到终端窗口，按 Ctrl + C。停掉之后再刷新浏览器，页面就打不开了——这就是“本地运行”的含义。

hello-node 这个文件夹留着还是删掉都行。留着的好处是，以后怀疑环境坏了，进来跑一次 pnpm dev 就能验证。

装完之后，你的电脑上多了什么

名字 干什么的 怎么确认它在
Node.js 运行 JS 代码的发动机 node -v
npm 自带的包管理器 npm -v
pnpm 本课用的包管理器 pnpm -v
node_modules/ 文件夹 项目里下载下来的几百个零件，体积很大，正常现象 进项目 ls 能看到
package.json 项目的零件清单 + 启动命令表 进项目 ls 能看到

node_modules 动辄几百 MB，不要手动去删里面的东西，也永远不要把它上传到网上——下一节配置 Git 时会自动帮你排除掉它。

四、完成的标志是

  • node -v 能打印版本号
  • npm -v 能打印版本号
  • pnpm -v 能打印版本号
  • （国内）pnpm config get registry 显示的是镜像地址
  • 我成功创建了 hello-node 项目并执行了 pnpm dev
  • 我在浏览器 localhost:3000 看到了页面
  • 我用 Ctrl + C 把它停掉了，并确认页面打不开了
  • 我说得清 package.json 和 node_modules 分别是什么

五、卡住了看这里

本节是全课最容易卡住的一节。下面五条覆盖了 90% 的情况；还不行就去 [附录 F 环境安装疑难解答]，或者用第六部分的提示词把报错原文喂给 AI。

Q：装完了，但 node -v 提示 command not found / 不是内部或外部命令。 按顺序试：① 关掉终端重开一个——八成的情况这一步就好了，安装程序修改的环境变量对已经开着的窗口不生效；② 还不行就重启电脑；③ 再不行说明 PATH 没配上，Windows 用户重新运行安装包选 Repair，Mac 用户去官网重新下载 .pkg 装一遍。

Q：Windows 执行 npm install -g pnpm 报 无法加载文件 ... 因为在此系统上禁止运行脚本。 PowerShell 默认禁止运行脚本。以管理员身份打开 PowerShell（开始菜单右键 PowerShell → 以管理员身份运行），执行：

终端窗口
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

输入 Y 确认。然后关掉管理员窗口，开一个普通窗口重试。

Q：Mac 执行 npm install -g pnpm 报 EACCES: permission denied。 权限问题。先别急着加 sudo（加了以后会引出更多权限问题）。改用这条：

终端窗口
corepack enable pnpm

如果 corepack 也不存在，再用 sudo npm install -g pnpm，输开机密码。

Q：pnpm create next-app 卡住不动，或者报网络超时 / ETIMEDOUT / ECONNRESET。 网络问题，不是你操作错了。① 先做第 4 步的镜像源配置；② 按 Ctrl + C 停掉，把刚才生成到一半的文件夹删掉，重新执行一次（重试非常有效）；③ 如果你开着代理软件，试试关掉再装，或者反过来开着装。

Q：pnpm dev 报 Port 3000 is already in use / 端口被占用。 说明你之前开的服务还在跑。① 找到那个老终端窗口按 Ctrl + C；② 找不到就直接用别的端口：pnpm dev -- -p 3001，然后访问 localhost:3001。

Q：浏览器打开 localhost:3000 显示“无法访问此网站”。 ① 看终端里是不是真的出现了 Ready——如果终端在报红字，问题在终端不在浏览器；② 确认你没在别的窗口按过 Ctrl + C；③ 地址别写成 https://localhost:3000，本地服务是 http，多一个 s 就打不开。

Q：node_modules 太大了，能删吗？ 能。删掉之后在项目目录执行 pnpm install 就会重新下载回来。它是可再生资源，这也是为什么它永远不需要备份、不需要上传。

六、本节提示词

① 安装报错急救（本节最该存的一条）：

我在给电脑装 Node.js / pnpm 环境，卡住了。
我的系统：【Mac，芯片是 Apple M 系列 / Intel】或【Windows 11】
我执行的命令是：【粘贴命令】
完整报错信息如下：
【粘贴终端里的全部输出，不要只截一行，不要删减】


请你：
1. 用大白话告诉我这是什么问题；
2. 给我一条条可以直接复制执行的命令来解决，并说明每条在做什么；
3. 如果有多种解法，先给最安全、最不容易引出新问题的那一种；
4. 明确告诉我做完之后怎么验证成功了。

② 环境体检（怀疑环境坏了的时候用）：

我想确认我的开发环境是完整的。请给我一组检查命令（我用的是【Mac / Windows】），
每条命令后面写清楚：正常的输出应该长什么样、如果输出不对说明什么问题。
检查范围：Node.js、npm、pnpm、Git，以及 npm 的 registry 配置。

③ 看懂 package.json（进了项目一脸懵的时候）：

这是我项目里的 package.json 文件内容：
【粘贴文件全文】


请用零基础能懂的话告诉我：
1. 这个项目是用什么技术做的；
2. scripts 里每一条命令我该在什么时候用，分别是做什么的；
3. dependencies 里有没有需要我特别注意的东西。

上一节 ← 2.1 认识终端 下一节 → 2.3 Git 与 GitHub：AI 编程「后悔药」四件套