什么是 npm？package.json 和 lockfile 各自的作用是什么？

Question

Accepted Answer

**npm**（Node Package Manager）是 Node 默认的工具，用于安装和管理第三方包（依赖）以及运行项目脚本。两个文件定义了一个项目：**`package.json`**（清单文件）和 **`package-lock.json`**（精确的依赖树）。

## package.json —— 项目清单

```json
{
  "name": "my-app",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "start": "node server.js",
    "dev": "nodemon server.js",
    "test": "vitest"
  },
  "dependencies": {        // needed at RUNTIME
    "express": "^4.18.0"
  },
  "devDependencies": {     // needed only for DEVELOPMENT (testing, building)
    "vitest": "^1.0.0"
  }
}
```

它记录了元数据、脚本和依赖。`^4.18.0` 是一个 **semver 范围**——`^` 允许兼容的次版本/补丁更新（4.x.x，但不包括 5.0.0）。

## lockfile —— 精确、可复现的安装

```text
package.json says:  express ^4.18.0  (a RANGE — could install 4.18.0 or 4.19.2...)
package-lock.json:  express 4.18.2   (the EXACT version + every nested dependency)
```

lockfile 锁定了每个已安装包（包括传递依赖）的**精确**版本。这保证了团队中的每个人——以及 CI 和生产环境——都能得到*完全相同*的依赖树，从而避免因版本漂移导致的“在我机器上能跑”这类 bug。

## 关键命令

```bash
npm install              # install all deps from package.json (updates lockfile)
npm install express      # add a dependency
npm install -D vitest    # add a devDependency
npm ci                   # install EXACTLY from the lockfile (used in CI — fast, strict)
npm run dev              # run a script defined in package.json
```

`npm ci`（相对于 `npm install`）严格按照 lockfile 安装且不修改它——这是用于 CI/生产环境可复现性的正确命令。

## 提交 lockfile

```text
✓ ALWAYS commit package-lock.json → reproducible installs across the team & CI
```

## 为什么这很重要

npm 和这两个文件是每个 Node 项目的基石。

理解 `package.json`（dependencies 与 devDependencies、semver 范围、脚本），尤其是**为什么需要 lockfile**（对整个依赖树进行确定性、可复现的安装）至关重要——提交 lockfile 并在 CI 中使用 `npm ci`，可以防止因队友或生产环境获得不同包版本而引发的隐蔽且难以排查的故障。