众元AI学习空间

05_Nodejs与npm安装验收手册

5分钟阅读

Node.js 与 npm 安装验收手册

首次使用：W03-D03“最小 API Consumer”。

当前代码合同：frontend/package.json 要求 Node.js >=24.14.0 <25、npm >=11.9.0 <12。

推荐：安装满足合同的 Node 24 LTS。官方下载页未来可能把其他主版本标为 LTS，所以必须同时核对 Node.js 下载页 和项目 engines，不能只点“最新版”。

1. 先检查现状

彻底新开一个 TRAE PowerShell 终端：

node --version
npm.cmd --version
where.exe node
where.exe npm

判断：

结果下一步
Node 为 24.x 且 >=24.14.0，npm 为 11.x 且 >=11.9.0不重复安装，直接进入第 3 节
版本不满足项目 engines安装满足合同的 Node 24 LTS
node 找不到按第 2 节安装
npm 报 PowerShell 脚本策略错误使用 npm.cmd；不要为了一个命令修改全局执行策略
where.exe node 出现多套来源记录并确认实际使用哪一套；课堂不同时引入 nvm/fnm 等版本管理器

2. 安装官方 LTS

  1. 打开 Node.js 官方下载页。
  2. 选择满足项目 engines 的 Node 24 LTS Windows 64 位安装器。不要选 Current、EOL、源码包或非官方安装脚本。
  3. 双击 .msi 安装器。
  4. 接受许可证后保持标准组件：Node.js runtime、npm package manager、Add to PATH。
  5. 安装目录可保持默认；不要安装到课程项目文件夹。
  6. 若出现“Automatically install necessary tools”一类额外原生编译工具选项，本课程基础依赖通常不需要，先不额外安装大体积工具链；只有真实依赖编译错误并确认需要时再处理。
  7. 完成后彻底退出并重开 TRAE。
  8. 新开终端验收：
node --version
npm.cmd --version
where.exe node
node -e "console.log(process.execPath); console.log(process.platform, process.arch)"

版本必须满足项目 engines.node。

3. 在 W03 前端目录安装依赖

先进入包含 package.json 的目录。以项目结构为例：

Set-Location -LiteralPath .\frontend
Get-ChildItem package.json

检查合同：

node -e "const p=require('./package.json'); console.log(p.engines); console.log(p.scripts)"

若项目已经有可信的 package-lock.json：

npm.cmd ci

若学生刚从空目录创建、还没有 lockfile：

npm.cmd install

首次 npm install 会生成 package-lock.json。审查无误后应把 lockfile 提交到 Git，使同一课程项目可以复现依赖解析；不要提交 node_modules/。

.gitignore 至少包含：

node_modules/
dist/

4. 构建与浏览器验收

先构建：

npm.cmd run build

再启动开发服务器：

npm.cmd run dev

终端通常会给出 http://localhost:5173。浏览器打开后完成：

  1. 页面显示预期标题，而不是目录列表或空白页。
  2. F12 → Console 没有阻断性红错。
  3. F12 → Network 能看到真实前端资源；联调阶段还要看到真实 API 请求。
  4. 回到终端按 Ctrl + C 停止开发服务器。

通过标准不是“npm install 没报错”，而是 npm.cmd run build 成功且页面真实打开。

5. 常见故障

npm.ps1 cannot be loaded because running scripts is disabled

使用：

npm.cmd --version
npm.cmd install
npm.cmd run build

不需要执行 Set-ExecutionPolicy Unrestricted。

EBADENGINE

读取报错要求与当前版本：

node --version
node -e "console.log(require('./package.json').engines)"

若 Node 过旧，升级到满足合同的官方 LTS；不要删除 engines 字段来掩盖问题。

npm 网络、证书或代理错误

  • 保存第一条真实错误和 registry 地址。
  • 组织网络使用组织批准的代理/镜像。
  • 不运行关闭 TLS 校验的命令，不把永久 Token 写入 .npmrc 后提交。
  • 教师若准备离线缓存，需在同版本 Node、同 lockfile 上提前验证。

EADDRINUSE: 5173

旧开发服务器可能仍在运行。先回到旧终端 Ctrl + C。临时换端口只用于排错，最终联调仍按课程约定记录真实地址。

Cannot find package 或 node_modules 异常

确认当前目录真的包含 package.json。不要在课程根目录运行 npm。若依赖树损坏，先保留报错和 lockfile，教师确认后再决定是否重装；不要无条件删除用户其他项目的目录。

6. 提交证据

Node 版本：
npm 版本：
node.exe 路径：
项目 engines.node：
安装命令：npm.cmd ci / npm.cmd install
build 结果：
开发服务器地址：
浏览器 Console：
浏览器 Network：

反向链接