188 lines
6.9 KiB
Markdown
188 lines
6.9 KiB
Markdown
下面是基于目前生态（到 2025–2026 年）整理的 **npm 更新包相关指令实用总结**，只保留对日常开发真正有用的部分。
|
||
|
||
---
|
||
|
||
## 一、最核心的几个命令
|
||
|
||
### 1. 查看有哪些包需要更新：`npm outdated`
|
||
|
||
bash复制
|
||
|
||
`# 查看当前项目中有哪些依赖已过期 npm outdated # 查看指定包是否过期 npm outdated react # 查看全局安装包是否过期 npm outdated -g`
|
||
|
||
常见选项：
|
||
|
||
- `--all`：显示所有过时的依赖（包括间接依赖）
|
||
- `--json`：以 JSON 输出，便于脚本处理
|
||
- `--long`：显示更多信息（比如依赖类型、主页等）
|
||
- `-g / --global`：检查全局包
|
||
|
||
典型输出列含义：
|
||
|
||
- **Current**：当前安装版本
|
||
- **Wanted**：在 `package.json` 的 semver 范围内，能接受的最高版本
|
||
- **Latest**：npm 上标记为 `latest` 的版本（不一定在 semver 范围内）
|
||
- **Location**：包在 `node_modules` 中的位置
|
||
|
||
**建议用法：**
|
||
|
||
> 每次更新前先跑一遍：
|
||
> `npm outdated`
|
||
> 看清楚「Current / Wanted / Latest」再决定怎么更。
|
||
|
||
---
|
||
|
||
### 2. 按 semver 规则更新依赖：`npm update`
|
||
|
||
bash复制
|
||
|
||
`# 更新当前项目下所有符合 semver 范围的依赖 npm update # 更新指定依赖（如 react） npm update react # 更新全局依赖 npm update -g`
|
||
|
||
关键点（非常重要）：
|
||
|
||
- **遵守 semver 范围**：
|
||
只会更新到 `package.json` 里版本范围（如 `^1.2.0`、`~1.2.0`）允许的**最高版本**。
|
||
- `^1.2.0` → 允许 `1.x.x`，不会升到 `2.0.0`
|
||
- `~1.2.0` → 允许 `1.2.x`，不会升到 `1.3.0`
|
||
- **默认不改 `package.json` 的范围**：
|
||
实际安装版本可能变新，但 `package.json` 的版本范围通常不会自动被改。要一并更新范围：
|
||
|
||
bash复制
|
||
|
||
`npm update --save`
|
||
|
||
- **会更新 `package-lock.json` / lockfile**：
|
||
所以建议更新前先 commit 一次，方便对比变更。
|
||
|
||
常用选项：
|
||
|
||
- `--save`：同步更新 `package.json` 里的版本范围
|
||
- `--no-save`：只更新锁文件 & 实际安装版本，不改 `package.json`
|
||
- `--dry-run`：只预览将要发生的变更，不真正安装
|
||
- `-g / --global`：更新全局包
|
||
- `--workspace` / `--workspaces`：在 monorepo/workspace 中定向更新
|
||
|
||
**实用场景：**
|
||
|
||
- 日常小版本更新（补丁/次版本）：
|
||
|
||
bash复制
|
||
|
||
`npm outdated npm update # 只在 semver 范围内升级 npm test`
|
||
|
||
- 希望顺带更新 `package.json` 里的版本范围：
|
||
|
||
bash复制
|
||
|
||
`npm update --save`
|
||
|
||
|
||
---
|
||
|
||
### 3. 指定版本直接安装：`npm install`
|
||
|
||
当你想「**跳过 semver 限制，直接上到某个指定版本**」时，用 install 更直观：
|
||
|
||
bash复制
|
||
|
||
`# 升级/降级到特定版本 npm install react@18.2.0 # 升级到某个主版本最新（如 v18 内最高） npm install react@18 # 全局包升级到最新 npm install -g typescript@latest`
|
||
|
||
特点：
|
||
|
||
- **同时更新 `package.json` 和 `package-lock.json`**
|
||
- 适合：
|
||
- 精确锁某个版本
|
||
- 从 v17 直接跳到 v18 等大版本升级
|
||
- 需要回滚某个依赖时
|
||
|
||
---
|
||
|
||
## 二、批量升级到最新版本：npm-check-updates（ncu）
|
||
|
||
> 适合「我想把项目所有依赖都调到最新，连主版本也愿意跟」的场景。
|
||
|
||
### 1. 安装与基础用法
|
||
|
||
bash复制
|
||
|
||
`# 全局安装（推荐） npm install -g npm-check-updates # 1）查看有哪些更新（包括超出当前 semver 范围的） ncu # 2）修改 package.json 的版本号到可用的最新版本 ncu -u # 3）按新的版本范围真正安装依赖 npm install`
|
||
|
||
要点：
|
||
|
||
- `ncu / npm-check-updates` **只改 `package.json`**，不安装，需要再跑一遍 `npm install`。
|
||
- 会**无视原来的版本范围**，直接把依赖范围改到更高的版本（默认相当于“更新到最新稳定版”）。
|
||
|
||
### 2. 常用参数（非常实用）
|
||
|
||
bash复制
|
||
|
||
`# 只更新部分包 ncu --filter react* # 只更新包名以 react 开头的 ncu --reject webpack # 排除 webpack 不更新 # 控制更新粒度 ncu --target patch # 只升补丁版本 ncu --target minor # 升 minor & patch（但不升主版本） ncu --target latest # 默认，相当于更新到最新稳定 # 交互式选择（强烈推荐） ncu -i # 逐条确认要不要升 # 对全局依赖 ncu -g`
|
||
|
||
**推荐安全流程：**
|
||
|
||
bash复制
|
||
|
||
`# 1. 查看差异 ncu # 2. 交互式选择升级（建议先只升 patch / minor） ncu -i --target minor # 3. 真实安装 npm install # 4. 跑测试 npm test`
|
||
|
||
---
|
||
|
||
## 三、Yarn / pnpm 中对应的更新命令（简略对照）
|
||
|
||
如果你项目用的不是 npm，而是 yarn 或 pnpm，可以类比使用：
|
||
|
||
### Yarn
|
||
|
||
bash复制
|
||
|
||
`# 根据 package.json 的范围更新依赖 yarn upgrade # 指定包 yarn upgrade react # 忽略范围，强制升到 latest yarn upgrade react --latest # 交互式更新（体验类似 ncu -i） yarn upgrade-interactive yarn upgrade-interactive --latest`
|
||
|
||
### pnpm
|
||
|
||
bash复制
|
||
|
||
`# 按范围更新 pnpm update pnpm update react # 升到 latest 标签对应的版本（可能跨主版本） pnpm update --latest pnpm update react --latest # monorepo 里递归更新所有子包 pnpm update -r pnpm update -r --latest`
|
||
|
||
---
|
||
|
||
## 四、推荐的「更新套路」示例
|
||
|
||
### 场景 1：日常小步更新（推荐默认策略）
|
||
|
||
bash复制
|
||
|
||
`# 1. 看有哪些包过期 npm outdated # 2. 按 semver 规则更新到范围内最新 npm update # 3. 跑测试 npm test # 4. 如一切正常，提交： git commit -am "chore: npm update"`
|
||
|
||
---
|
||
|
||
### 场景 2：想把项目整体抬到“尽量新”的版本
|
||
|
||
bash复制
|
||
|
||
`# 1. 先保证工作区干净（已提交） git status # 确保无未提交重要修改 # 2. 批量调整 package.json 的版本范围到最新可用 ncu -i # 交互选择想升的包 # 3. 按新范围安装 npm install # 4. 跑单测 / E2E / 手动 sanity check npm test # 5. 再决定是否提交 & 上线 git diff git commit -am "chore: bump deps with ncu"`
|
||
|
||
---
|
||
|
||
### 场景 3：解决某个安全漏洞（定点升级）
|
||
|
||
bash复制
|
||
|
||
`# 1. 安全扫描 npm audit # 2. 能自动修就自动修 npm audit fix # 3. 如果提示手动升级某个依赖： npm install <有漏洞的包>@<修复后的版本> # 例如 lodash@4.17.21`
|
||
|
||
配合 `npm outdated` 和 `ncu` 一起使用，可以更精确控制升级范围。
|
||
|
||
---
|
||
|
||
## 五、小结：常用命令速查
|
||
|
||
|命令|主要用途|是否修改 `package.json`|是否修改 lockfile|
|
||
|---|---|---|---|
|
||
|`npm outdated`|查看哪些包过期|否|否|
|
||
|`npm update`|在 semver 范围内更新到最新|否（加 `--save` 才改）|是|
|
||
|`npm install <pkg>@<ver>`|精确安装 / 升级某个版本|是|是|
|
||
|`ncu`|查看可用的最新版本（含跨主版本）|否|否|
|
||
|`ncu -u`|修改 `package.json` 的版本范围|是|否|
|
||
|`npm audit` / `npm audit fix`|安全扫描与自动修复|否|是|
|
||
|
||
---
|
||
|
||
如果你告诉我你的具体场景（比如：「React 单体项目」「pnpm monorepo」「只想升 patch」），我可以给出一套更精简的「项目专用更新脚本」或命令组合。 |