包管理器不是运行网站的魔法，它是项目的材料管理员
先认识 Package / 包
包是别人整理好、可以重复使用的一组代码。
AI 留言板可能使用：
text
react 构建页面
express 构建后端 API
zod 检查输入数据
vite 启动开发和构建前端你不需要自己从零写 React，但项目要声明使用哪个版本。
Dependency / 依赖是什么
如果项目代码必须依靠某个包才能运行，这个包就是项目依赖。
text
项目 一家餐厅
依赖 面粉、调料、烤箱等外部材料和工具
包管理器 根据清单采购并摆放材料的管理员依赖本身还可能依赖其他包，形成依赖树。
package.json 是清单
json
{
"scripts": {
"dev": "vite",
"build": "tsc && vite build"
},
"dependencies": {
"react": "^19.0.0",
"express": "^5.0.0"
},
"devDependencies": {
"typescript": "^5.0.0",
"vite": "^7.0.0"
}
}它记录需要什么，但不是已经安装好的包目录。
node_modules 是安装结果
运行安装命令后，包管理器会准备依赖。npm 和 Yarn 常在项目创建 node_modules；pnpm 也提供兼容的 node_modules 结构，但会更强调内容寻址存储和链接复用。
不要手动修改 node_modules。重新安装时会被覆盖。
锁文件为什么存在
package.json 里的版本范围可能允许多个版本。锁文件记录这次实际解析出的精确版本和依赖关系。
text
package-lock.json npm
pnpm-lock.yaml pnpm
yarn.lock Yarn锁文件应该提交 Git，让本地、同事电脑和部署平台尽量安装同一套依赖。
npm、pnpm、Yarn 是什么关系
它们都是 JavaScript 包管理器，都能：
text
读取 package.json
安装依赖
维护锁文件
运行 scripts区别主要在安装策略、锁文件格式、工作区能力和命令细节。
初学时最重要的不是争论哪个最好，而是跟随现有项目。
怎样判断项目使用哪一个
按顺序看：
- README 有没有指定命令。
- package.json 有没有
packageManager字段。 - 根目录是哪一种锁文件。
例如：
json
{
"packageManager": "pnpm@10.0.0"
}说明项目明确希望使用 pnpm 的某个版本线。
同一件事的命令对照
| 任务 | npm | pnpm | Yarn |
|---|---|---|---|
| 安装项目依赖 | npm install | pnpm install | yarn install |
| 启动 dev script | npm run dev | pnpm dev | yarn dev |
| 添加运行依赖 | npm install zod | pnpm add zod | yarn add zod |
| 添加开发依赖 | npm install -D vitest | pnpm add -D vitest | yarn add -D vitest |
| 删除依赖 | npm uninstall zod | pnpm remove zod | yarn remove zod |
具体命令以项目和当前官方文档为准。
为什么不要混用
项目已有 pnpm-lock.yaml，你又运行 npm install，可能生成 package-lock.json。
随后出现：
text
你的电脑按 npm 解析
同事电脑按 pnpm 解析
部署平台不知道该听谁
AI 又建议删除其中一个结果可能是版本差异、幽灵依赖或构建不一致。
看到现有锁文件，先使用对应工具。想迁移包管理器是一项独立工程，不是修一个小错误时顺手做的事。
npm install 到底发生什么
text
读取 package.json
↓
读取或生成 package-lock.json
↓
从包注册表获取所需包
↓
准备 node_modules
↓
运行允许的安装生命周期脚本所以不要在完全不信任的陌生项目里盲目安装。先看 README、package.json 的 scripts 和来源。
npm run dev 又是什么
它不是 npm 内置了每个框架。npm 去 package.json 的 scripts 找 dev：
json
{
"scripts": {
"dev": "vite"
}
}然后执行这个项目安装的 Vite 命令。
npx 是什么
npx 用来运行包提供的命令。常见：
bash
npx vite
npx create-vite它可能运行本地已安装包，也可能临时获取远程包。运行陌生命令前确认包名、来源和版本，尤其不要随便执行 AI 提供的拼写相近包名。
pnpm 对应常见 pnpm exec 或 pnpm dlx，Yarn 也有自己的运行方式。
安装失败怎样判断
command not found: pnpm
项目要求 pnpm，但电脑没有可用命令。先查看 pnpm 官方安装方式，不要改用 npm 逃避。
Cannot find module
可能依赖没安装、包没写入 package.json、导入路径错误或站错目录。
ERESOLVE 或 peer dependency 冲突
两个包对依赖版本要求不兼容。不要第一反应使用强制参数；先确认框架和包版本是否匹配。
本地能运行，部署缺包
可能只在电脑全局安装了某个工具，却没有记录进项目依赖；部署环境没有你的全局包。
官方参考
项目根目录已有 pnpm-lock.yaml，AI 建议直接运行 npm install。第一步应该照做吗？
答案：不应该。先查看 README 和 packageManager 字段；已有 pnpm 锁文件通常应该使用 pnpm，避免生成第二份锁文件和不同依赖树。