前置知识: JavaScript

npm 包管理：读懂现代项目的铁三角

5 min入门

以"项目从哪来"讲透 npm：package.json 身份证、node_modules 仓库、lockfile 锁定的铁三角关系，语义化版本解读，与脚本运行日常。

前置知识

心智模型：npm 是”超市 + 购物清单”的组合

现代 JS 项目几乎不从零写：HTTP 请求有现成的 axios，日期处理有 dayjs，框架本身也是别人发布的包。这些包统一发布在 npm 注册中心（registry.npmjs.org，一个存放百万级开源包的仓库）——这是”超市”。

npm 客户端（装 Node 时自带）就是购物执行者：你把需要的包写进清单，它负责下载、装好、记录版本。整个体系围绕三个天天见面的事物运转，先立住这个”铁三角”模型：

package.json     购物清单：项目叫什么、依赖哪些包（写"要什么"）
node_modules/    仓库货架：下载下来的包的真实代码（"拿到了什么"）
package-lock.json 成交记录：每个包实际安装的精确版本（"具体拿了哪一版"）

接下来从头跑一遍项目，三个角色会依次登场。

第一步：npm init——给项目发身份证

mkdir my-app && cd my-app
npm init -y

-y 表示全部采用默认值（不加则逐项问答）。执行后目录里出现 package.json：

{
  "name": "my-app",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  }
}

现在它很朴素，但注意两点：这个文件是项目的”身份证 + 购物清单”，之后每装一个依赖都会登记进它的 dependencies；scripts 字段是你定义自己命令的地方（马上用到）。真实项目里你会手工维护 name/version/description，但依赖部分永远让 npm 管理。

第二步：npm install——购物与货架

npm install dayjs          # 安装一个真实的包（日期处理库）

一秒钟后发生了很多事，逐一对照铁三角：

  1. node_modules/ 出现了：dayjs 的代码（以及它依赖的包）被下载放进这个目录——“货架”建起来了；
  2. package.json 多了一行："dependencies": { "dayjs": "^1.11.13" }——清单登记了”本项目依赖 dayjs”；
  3. package-lock.json 出现了：成交记录，写明这次实际装的是 1.11.13 这个精确版本。

立刻试用：

// index.js
const dayjs = require('dayjs');   // 或 import dayjs from 'dayjs'（ESM 项目）
console.log(dayjs().format('YYYY-MM-DD HH:mm'));
node index.js    # 输出当前日期时间——第一个第三方依赖跑通了

两类依赖的分界要在此立好规矩：

npm install vite            # 进 dependencies：运行时要用（框架、工具库）
npm install -D eslint       # 进 devDependencies：只在开发期用（测试、检查、构建）

区分的价值在协作与部署：生产部署只需要 dependencies 的东西，dev 依赖不必装。

第三步：读懂版本号里的”^”

刚才清单里写的 ^1.11.13 不是精确版本，是语义化版本（semver）+ 兼容范围：

主版本.次版本.修订号   例如 2.3.1
  ^2.3.1  允许装 2.x.x 里最新的（次版本/修订号升级——向后兼容的更新）
  ~2.3.1  只允许 2.3.x（仅修订号升级）
  2.3.1   死锁精确版本

设计意图：依赖作者承诺”主版本变更才可能有破坏”，所以 npm 默认允许自动获得兼容范围内的新修复。但”允许浮动”也埋下了团队不一致的种子——你周一装的 2.3.1，同事周三装成了 2.4.0，代码却”在我机器上是好的”。救场的正是铁三角的第三角：

package-lock.json 把每个人、每次安装都锁死在同一组精确版本上。所以团队规范只有一条：package-lock.json 必须提交进 git；装依赖用 npm ci（严格按 lockfile 装）或常规 npm install，但永远不要手改 lockfile、不要不提交它。

日常高频操作：其实只有五个

npm install                # 按清单+锁文件装齐全部依赖（克隆项目后的第一件事）
npm install <包名>          # 添加运行依赖
npm install -D <包名>       # 添加开发依赖
npm run <脚本名>            # 运行 package.json scripts 里定义的命令
npm uninstall <包名>        # 卸载（清单与货架同步清理）

npm run 值得多说一句：scripts 里定义的键就是可执行的自定义命令，npm run dev、npm run build 是每个前端项目的日常入口——框架脚手架生成项目时，就是在这里预置了这些命令（你到 Vite 快速上手 会立刻重逢）。

恢复现场：为什么”删掉 node_modules 重装”是万能偏方

node_modules 有两个臭名昭著的特点：巨大（轻松几百 MB）与可重建（清单 + 锁文件在，随时 npm install 完整复原）。由此推出两条工程铁律：

  1. node_modules 不提交 git（.gitignore 默认排除它）——它可以从清单精确重建；
  2. 遇到”依赖行为诡异”的玄学问题时，删除 node_modules + package-lock.json 后 npm install 是标准的现场重建——因为货架上的实际内容可能因中断的安装而残缺。

顺带理解了为什么 npm 慢与占空间：每个项目都完整复制一份依赖树。这正是 pnpm 等替代品（全局存储 + 硬链接共享）的卖点——入门期用 npm，遇到真实痛点再迁移。

动手环节：从零跑通一个”包项目”

mkdir npm-demo && cd npm-demo
npm init -y                       # 身份证
npm install dayjs                 # 运行依赖上架
npm install -D prettier           # 开发依赖上架

# 观察铁三角
ls node_modules/dayjs             # 货架真实存在
cat package.json                  # 两类依赖分列在 dependencies / devDependencies
cat package-lock.json | head -20  # 精确版本成交记录

# 写代码用依赖（index.js 同上文 dayjs 示例），跑通
node index.js

# 运行自定义脚本：先在 package.json 的 scripts 里加一行 "today": "node index.js"
npm run today                     # 与 node index.js 等效——项目的统一入口习惯

# 模拟"克隆别人项目"的标准动作
rm -rf node_modules               # 删掉货架
npm install                       # 一条命令完整重建——清单+锁文件的威力
node index.js                     # 照常运行

常见困惑

“npm install 时报 EACCES / 权限错误？“——多半是历史遗留的全局目录权限问题（早期教程教你 sudo npm install -g，后患无穷）。项目内安装从不需要 sudo；全局安装出权限问题用 nvm 方案（版本管理）后自然消失。

“下载很慢/经常失败？“——registry 在海外。国内环境给 npm 换镜像源（npm config set registry https://registry.npmmirror.com），一条命令立竿见影；团队协作时注意 lockfile 里的 resolved 地址一致性问题。

“npm、pnpm、yarn 到底用哪个？“——三者客户端不同、超市同一个（都默认连 npm registry）。npm 入门无争议；pnpm 的磁盘与速度优势等项目多了再迁移，命令几乎一一对应，切换成本极低。

检验清单

  • 能画出 package.json / node_modules / lockfile 的铁三角并说出各自职责；
  • 完成从 npm init 到 npm run 的完整最小项目，并理解每步改动了铁三角的哪一角；
  • 能解释 ^ 版本范围与 lockfile”锁定精确版本”如何配合解决团队一致性问题；
  • 记住两条铁律：lockfile 必须提交、node_modules 永不入库；
  • 能解释”删 node_modules 重装”为什么是合法且万能的恢复手段。

下一步

依赖管理就位，该让工具链真正上岗了：进入 Vite 快速上手，用 npm create 三条命令拉起第一个现代前端项目——你会当场重逢本篇的全部概念。