前端工程化 / 系统课时
准备 Node.js 与包管理器
准备 Node.js 与包管理器
本课建立一套可复现的 Vite 8 安装基线:选择仍受支持的 Node.js LTS,统一 npm、pnpm 或 Yarn 及其锁文件,再用真实项目完成安装与构建验证。这样可以在进入配置排障前,先排除版本、PATH、仓库和依赖树不一致问题。
学习目标
- 选择满足 Vite 8 要求且仍在维护期的 Node.js 版本
- 为项目固定一种包管理器和对应锁文件
- 用命令验证终端、仓库、依赖安装与生产构建
选择受支持的 Node.js
Vite 8 的最低运行范围是 Node.js 20.19+ 或 22.12+。但最低可运行不等于适合作为新项目基线:Node.js 20 已结束官方维护,因此新项目优先使用 Node.js 24 LTS;仍在维护的旧项目也可以使用 Node.js 22 LTS。
不要把 Node.js Current 版本直接作为团队默认值。Current 适合提前验证兼容性,LTS 更适合作为开发机、CI 与生产构建环境的共同基线。团队应统一主版本,并确保终端实际命中的 node 与 IDE、CI 使用的是同一套安装。
统一包管理器与锁文件
npm、pnpm 和 Yarn 都能运行 Vite,关键是一个项目只选择一种,并提交它生成的锁文件。锁文件决定精确依赖树;混用工具会产生多份锁文件,导致本地、CI 与同事机器安装出不同结果。
| 包管理器 | 应提交的锁文件 | CI 或干净安装 |
|---|---|---|
| npm | package-lock.json |
npm ci |
| pnpm | pnpm-lock.yaml |
pnpm install --frozen-lockfile |
| Yarn | yarn.lock |
yarn install --immutable |
开发中新增或升级依赖时使用正常安装命令,让清单与锁文件一起更新。CI 中使用冻结安装命令,发现 package.json 与锁文件不一致就直接失败,而不是静默改写依赖树。
执行环境基线检查
下面以 npm 为例检查命令解析、版本、仓库访问、脚手架、依赖安装和生产构建。请在准备存放项目的父目录执行。
node --version
npm --version
npm config get registry
npm create vite@latest vite-env-check -- --template vanilla
cd vite-env-check
npm install
npm run build预期输出
v<NODE_VERSION>
<NPM_VERSION>
https://registry.npmjs.org/
Scaffolding project in <PATH>/vite-env-check...
vite v8.<MINOR>.<PATCH> building client environment for production...
✓ built in <TIME><NODE_VERSION> 应属于已选定的 Node.js 22 或 24 LTS,其他占位值会因环境变化。构建成功并生成 dist 目录,说明 Node.js、npm、网络仓库、Vite 脚手架和本机原生依赖均可工作。
使用 pnpm 或 Yarn 时,不要先用 npm 安装再切换工具。应删除测试目录重新创建,并分别使用 pnpm create vite、pnpm install、pnpm build,或 yarn create vite、yarn install、yarn build 完成同等验证。
固化项目版本约束
可以在 package.json 中声明 Node.js 范围和包管理器版本。下面是片段示例,<NPM_VERSION> 必须替换为团队实际执行 npm --version 得到的完整版本号。
{
"engines": {
"node": "^22.12.0 || ^24.0.0"
},
"packageManager": "npm@<NPM_VERSION>"
}engines 用于向安装工具和部署平台表达兼容范围,packageManager 用于记录项目期望的工具及版本。它们不能替代版本管理器或 CI 镜像约束,仍应在开发文档、容器镜像或流水线中固定实际 Node.js 主版本。
验证配置时,从干净目录重新安装依赖并执行构建。npm 项目应提交 package-lock.json 后运行以下命令,确保锁文件可以独立恢复依赖树。
rm -rf node_modules
npm ci
npm run build预期输出
added <COUNT> packages, and audited <COUNT> packages in <TIME>
vite v8.<MINOR>.<PATCH> building client environment for production...
✓ built in <TIME>Windows PowerShell 可用 Remove-Item node_modules -Recurse -Force 替代 rm -rf node_modules。<COUNT> 和 <TIME> 是动态值;重点是 npm ci 没有改写锁文件,且构建再次成功。
处理典型环境失败
node: command not found 或“不是内部或外部命令”表示终端 PATH 中没有 Node.js。重新打开终端并检查版本管理器是否已加载,不要仅因为 IDE 能运行就认定系统终端也正确。
出现 Unsupported engine 时,先执行 node --version,确认当前会话没有命中旧版本。多版本管理器环境中,常见根因是项目目录未切换版本、终端启动脚本未生效,或 CI 镜像仍使用旧标签。
出现锁文件冲突时,只保留所选包管理器对应的锁文件,再用该工具重新安装并提交变更。不要手工编辑锁文件,也不要在 CI 中使用会自动更新锁文件的普通安装命令掩盖不一致。
安装超时、证书或 401 错误通常属于仓库、代理或认证问题。先检查 npm config get registry 与项目、用户级 .npmrc,再确认代理、私有仓库令牌和企业证书是否在当前终端与 CI 中一致。