包管理 & 依赖
🎯 学完这课你能
- 理解 package.json 是什么、怎么读
- 区分 dependencies 和 devDependencies
- 知道 npm install 出错时怎么排查
你以后看到一个项目跑不起来，先别急着怀疑代码写坏了。很多时候只是依赖没装齐、版本没对上，或者每个人装到的不是同一套东西。
你做绩效系统时，有没有注意到 node_modules 文件夹里有几千个文件夹？你可能想："我就做了一个小系统，怎么需要这么多东西？"
因为现代软件开发不是从零开始造一切。你的项目依赖了很多别人写好的工具——就像公司不会自己造办公桌、电脑、空调，而是从外面采购。
package.json = 项目的人员编制表 + 预算表
npm / yarn / pnpm = 采购部（负责下单和到货检查）
node_modules = 外包团队的工位区（它们实际坐的地方）
依赖（dependency） = 你需要的外包服务
很多项目代码本身都在，但真正“能运行”的那批依赖没有跟着 Git 一起下来，所以第一步通常是 npm install。
依赖安装失败时，不少问题不是包坏了，而是你的 Node.js 版本和项目要求不匹配。
像 React、Next.js 这种上线后还要用到的，属于正式依赖；像 ESLint、测试工具这类开发辅助，才更像 devDependencies。
那里只是装好的结果，不是项目真正的“源头配置”。要解决依赖问题，还是要回到 package.json 和 lock 文件。
读懂 package.json
打开你绩效项目的 package.json，它大概长这样：
= 正式员工。项目上线后还需要的。没有它们，系统跑不起来。
= 实习生 / 临时工。只在开发时需要（代码检查、测试工具等），上线后不需要。
版本号的秘密
你注意到版本号前面有个 ^ 符号吗？版本号遵循 semver（语义化版本） 规则：
^16.0.0 = 接受 16.x.x 的任何版本（允许小更新和补丁）
~16.0.0 = 只接受 16.0.x（只允许补丁更新）
16.0.0 = 锁死这个版本，不允许任何更新
版本号 = 合同条款
- Major 升级 = 签了全新的外包合同（可能需要大量对接调整）
- Minor 升级 = 外包团队增加了新服务（不影响已有合作）
- Patch 升级 = 外包团队修复了之前的工作失误（必须接受的修补）
npm 常见命令
npm install（或 npm i）
根据 package.json 采购所有外包团队。克隆项目后第一件事就是跑这个。
npm install axios
新采购一个叫 axios 的工具（用来发 HTTP 请求）。会自动加到 package.json。
npm run dev
执行 scripts 里定义的 "dev" 命令。通常是启动本地开发服务器。
npm run build
编译打包——把源代码变成可以上线的产物。就像把手稿排版印刷成书。
为什么 npm install 会出错？
这可能是你最常遇到的问题之一。常见原因：
A 工具要求用 React 18，B 工具要求 React 19——就像两个外包团队要求不同版本的办公软件，装不到一起。
有些包要求特定版本的 Node.js（运行环境）。就像某些软件只能在 Mac 上跑。
npm 从国外服务器下载，有时候网不好。可以配置国内镜像（淘宝镜像）。
"npm install 报错了，错误信息是 [复制关键行]。我的 Node.js 版本是 [node -v 的结果]。"
lock 文件：精确到每一个人
你可能见过 package-lock.json（或 yarn.lock / pnpm-lock.yaml）——这个文件动辄几千行，看起来吓人。
其实它的作用很简单：
package.json 说："我需要一个前端框架，React 19.x 都行"
package-lock.json 说："就用 React 19.0.4，它依赖的 scheduler 用 0.25.0"
编制表 vs 入职花名册：
- package.json = "需要 3 个前端工程师"（编制要求）
- lock 文件 = "张三、李四、王五，工号 001/002/003"（精确到人）
这样保证你和 CC 用的是完全相同的版本，避免"在我电脑上能跑"的尴尬。
装包失败时，先查哪四项
先跑 node -v。很多安装报错不是包坏了，而是运行环境太新、太旧，或者不符合项目要求。
下载超时、连接失败，多半是网络；报 peer dependency、版本不兼容，多半是依赖关系没对上。
如果两者长期不同步，或者你手动改了一个没更新另一个，很容易出现别人能装、你装不上的情况。
不要只说“npm install 失败了”。把关键几行原文、Node 版本、你刚才装了什么一起给出来，定位会快很多。
📝 小测验
你刚从 GitHub 克隆了一个项目，第一步应该做什么？
📝 小测验 2
devDependencies 和 dependencies 的区别是？