npm 核心命令实战（超详细版）npm 核心命令实战（超详细版）目录 npm init

npm 核心命令实战（超详细版）

本教程将围绕日常开发中最常用的 npm 命令，提供完整参数说明 + 真实案例 + 进阶技巧，让你在实战中得心应手。
每个命令都会附带多个示例，覆盖常见场景。

npm init – 初始化项目
npm install / npm i – 安装依赖
npm uninstall – 卸载依赖
npm update – 更新依赖
npm outdated – 检查过期依赖
npm list / npm ls – 查看已安装的依赖树
npm run – 执行脚本
npm test / npm start – 常用脚本快捷方式
npm ci – 快速可重现安装
npm audit – 安全审计与修复
npm dedupe – 去重依赖
npm link – 本地开发链接
npm config – 配置管理
npm cache – 缓存管理
npm doctor – 环境诊断
npm exec / npx – 执行包命令
npm publish / npm unpublish – 发布与撤销
npm version – 版本管理
npm deprecate – 弃用包
npm view – 查看包信息
npm search – 搜索包
npm whoami / npm adduser / npm login – 身份认证
npm logout – 退出登录
npm pack – 打包为 tarball
npm rebuild – 重新编译
npm prune – 清理多余包
npm docs / npm repo – 快速打开文档/仓库
npm bugs – 打开 issues 页面
npm explore – 进入包目录交互
npm diff – 对比包版本差异

1. `npm init` – 初始化项目

创建 package.json 文件，是所有 npm 项目的起点。

基础用法

# 交互式创建（会逐个提问）
npm init

# 跳过提问，使用默认值快速创建
npm init -y
npm init --yes

自定义初始值（通过配置）

# 设置默认作者、许可证等（永久生效）
npm config set init-author-name "张三"
npm config set init-author-email "zhangsan@example.com"
npm config set init-license "MIT"

# 然后执行 npm init -y 生成的 package.json 就会包含这些信息

使用自定义模板

创建 ~/.npm-init.js 文件，可以动态生成更复杂的 package.json。

// ~/.npm-init.js
module.exports = {
  name: prompt('package name', basename || process.cwd()),
  version: '0.0.1',
  description: prompt('description', 'My awesome project'),
  main: 'index.js',
  scripts: {
    test: 'jest',
    start: 'node index.js'
  },
  keywords: [],
  author: 'Zhang San <zhangsan@example.com>',
  license: 'MIT',
  dependencies: {},
  devDependencies: {}
}

实际案例

# 1. 新建项目目录
mkdir my-express-app
cd my-express-app

# 2. 快速初始化
npm init -y

# 3. 手动修改 package.json 中的入口文件为 server.js
# 或创建时指定：npm init -y --init-main=server.js （需事先配置）

2. `npm install` / `npm i` – 安装依赖

最核心的命令，用于安装项目依赖或全局工具。

基本安装形式

命令	说明	示例
`npm install`	根据 `package.json` 安装所有依赖	`npm i`
`npm install <pkg>`	安装指定包，并默认添加到 `dependencies`	`npm i lodash`
`npm install <pkg>@<version>`	安装特定版本	`npm i lodash@4.17.21`
`npm install <pkg>@latest`	安装最新版本	`npm i react@latest`
`npm install <pkg>@<tag>`	安装特定标签（如 `beta`, `next`）	`npm i vue@next`
`npm install <git url>`	从 git 仓库安装	`npm i git+https://github.com/user/repo.git`
`npm install <tarball file>`	从 `.tgz` 文件安装	`npm i ./local-package-1.0.0.tgz`
`npm install <folder>`	从本地文件夹安装（类似软链）	`npm i ../my-lib`

保存依赖的选项

# 保存到 dependencies (默认)
npm install express --save-prod   # 或 -P (npm 6+ 默认就是 --save)
npm install express               # 等价于 npm i express --save-prod

# 保存到 devDependencies
npm install jest --save-dev       # 简写: -D

# 保存到 optionalDependencies (可选依赖，安装失败不中断)
npm install puppeteer --save-optional   # 简写: -O

# 保存到 bundleDependencies (发布时一起打包，不常用)
npm install something --save-bundle      # 简写: -B

# 不保存到 package.json (仅临时安装)
npm install lodash --no-save

全局安装

# 全局安装 CLI 工具
npm install --global nodemon   # 简写: -g

# 指定全局安装目录（需事先配置 npm config set prefix）
npm install -g pm2 --prefix ~/.my-global

安装选项控制

# 忽略 package-lock.json，重新计算依赖
npm install --no-package-lock

# 仅安装生产依赖（跳过 devDependencies）
npm install --only=production   # 或 --omit=dev

# 强制重新下载，不利用缓存
npm install --force

# 静默安装（不输出日志）
npm install --silent

# 详细日志输出（用于调试）
npm install --verbose

# 安装时显示进度条
npm install --progress

# 禁用进度条
npm install --no-progress

实际案例

# 场景1: 新项目克隆后安装所有依赖
git clone some-project
cd some-project
npm install   # 安装 dependencies + devDependencies

# 场景2: 添加生产依赖
npm install express mongoose

# 场景3: 添加开发依赖
npm install --save-dev nodemon eslint prettier

# 场景4: 安装指定版本并锁定
npm install webpack@5.88.0

# 场景5: 从 GitHub 私有仓库安装（需要 SSH key 或 token）
npm install git+ssh://git@github.com:mycompany/private-lib.git

# 场景6: 安装并保存到 optionalDependencies
npm install pdfkit --save-optional

# 场景7: 全局安装 TypeScript 编译器
npm install -g typescript
tsc --version   # 验证

# 场景8: 开发时临时使用某个包（不写入 package.json）
npm install --no-save chalk

关于 `package-lock.json`

npm 5+ 会自动生成/更新 package-lock.json，用于锁定精确版本。
永远提交 package-lock.json 到版本库（除非你使用 npm shrinkwrap）。
可以使用 npm shrinkwrap 生成 npm-shrinkwrap.json（优先级高于 package-lock.json）。

3. `npm uninstall` – 卸载依赖

移除已安装的包，并可选择从 package.json 中删除记录。

基本用法

# 卸载本地包，并从 package.json 中移除（默认）
npm uninstall lodash          # 等价于 npm remove lodash

# 卸载开发依赖
npm uninstall jest --save-dev   # 或 -D

# 卸载全局包
npm uninstall -g nodemon

# 仅删除 node_modules 中的包，但保留 package.json 中的记录（极少用）
npm uninstall lodash --no-save

批量卸载

npm uninstall express lodash chalk
npm uninstall -g eslint prettier

卸载所有依赖（清空 node_modules）

# 方法1：逐个卸载（不推荐）
npm uninstall `npm list --depth=0 --parseable | grep node_modules | xargs`

# 方法2：直接删除目录（更快）
rm -rf node_modules   # Windows: rmdir /s node_modules

# 然后可选删除 package-lock.json
rm -f package-lock.json

实际案例

# 场景1: 不再使用 axios，改为使用 fetch
npm uninstall axios

# 场景2: 移除开发依赖 babel
npm uninstall @babel/core @babel/preset-env --save-dev

# 场景3: 清理全局安装的旧版 webpack
npm uninstall -g webpack@4

4. `npm update` – 更新依赖

将当前项目中的包更新到符合 package.json 中版本范围的最新版本。

基本用法

# 更新所有包（遵从 semver 范围）
npm update

# 更新单个包
npm update lodash

# 更新全局包
npm update -g nodemon

# 仅更新生产依赖
npm update --only=production

# 仅更新开发依赖
npm update --only=dev

与 `npm install <pkg>@latest` 的区别

npm update 不会突破 package.json 中定义的版本范围（例如 ^1.2.3 不会升级到 2.0.0）。
npm install lodash@latest 会安装最新版并重写 package.json 中的版本号。

实际案例

# 场景1: 定期维护项目依赖，获取小版本修复
cd my-project
npm outdated   # 先看看哪些可以更新
npm update     # 全部更新到符合范围的最新版

# 场景2: 只更新 express 到次要版本
npm update express

# 场景3: 更新全局工具
npm update -g npm

5. `npm outdated` – 检查过期依赖

查看哪些依赖有更新版本可用，并显示当前版本、符合范围的版本、最新版本。

输出格式

Package   Current  Wanted  Latest  Location
lodash    4.17.20  4.17.21 4.17.21 my-project
express   4.17.1   4.18.2  4.18.2  my-project

Current: 当前已安装的版本
Wanted: 符合 package.json 版本范围的最大版本
Latest: 该包在 npm 仓库中的最新版本

常用选项

# 仅列出生产依赖
npm outdated --only=production

# 仅列出开发依赖
npm outdated --only=dev

# 详细输出（显示更多列）
npm outdated --long

# 仅输出全局包
npm outdated -g --depth=0

# 以 JSON 格式输出（便于脚本处理）
npm outdated --json

实际案例

# 场景1: 检查项目依赖健康状况
npm outdated
# 如果有包显示 Wanted < Latest，说明有 major 版本可升级（但需小心）

# 场景2: 生成可操作的更新列表
npm outdated --json > outdated.json

# 场景3: 配合 npx npm-check-updates 自动升级
npx npm-check-updates -u   # 会修改 package.json 中的版本号
npm install

6. `npm list` / `npm ls` – 查看已安装的依赖树

显示所有已安装的包及其依赖关系。

基本用法

# 显示当前项目依赖树
npm list
npm ls

# 显示全局包
npm list -g

# 限制显示深度（默认无穷）
npm list --depth=0           # 只显示直接依赖
npm list --depth=1           # 显示直接依赖 + 子依赖

# 显示指定包的信息
npm list lodash

# 以解析过的扁平结构显示
npm list --parseable

# 以 JSON 格式输出
npm list --json

# 只显示生产依赖
npm list --prod

# 只显示开发依赖
npm list --dev

实际案例

# 场景1: 查看项目顶层有哪些直接依赖
npm list --depth=0

# 场景2: 检查为什么安装了某个包（查找依赖链）
npm list eslint  # 会显示是谁依赖了 eslint

# 场景3: 查看全局安装了哪些 CLI 工具
npm list -g --depth=0

# 场景4: 导出依赖树供分析
npm list --json > tree.json

常见输出示例

my-app@1.0.0 /home/user/my-app
├── express@4.18.2
│   ├── accepts@1.3.8
│   ├── array-flatten@1.1.1
│   └── ...
├── lodash@4.17.21
└── nodemon@2.0.20 (dev)

7. `npm run` – 执行脚本

运行 package.json 中 scripts 字段定义的命令。

定义脚本（在 package.json）

{
  "scripts": {
    "start": "node server.js",
    "dev": "nodemon server.js",
    "build": "webpack --mode production",
    "test": "jest",
    "lint": "eslint src/",
    "clean": "rm -rf dist",
    "prebuild": "npm run clean",
    "postbuild": "echo 'Build completed!'"
  }
}

执行脚本

# 运行自定义脚本
npm run dev
npm run build

# 传递参数给脚本（使用 -- 分隔）
npm run test -- --coverage   # 实际执行 jest --coverage
npm run build -- --watch      # webpack --mode production --watch

# 查看所有可用的脚本
npm run

# 以静默模式运行（不输出 npm 前缀信息）
npm run --silent build

# 运行生命周期钩子（pre/post 会自动触发，无需手动）
npm run build   # 会自动依次执行 prebuild -> build -> postbuild

内置脚本快捷方式

以下脚本可以省略 run：

npm start
npm test
npm stop
npm restart（会执行 stop、restart、start）

npm start      # 等价于 npm run start
npm test       # 等价于 npm run test

在脚本中使用环境变量

{
  "scripts": {
    "start": "NODE_ENV=production node app.js",        // Unix/Linux/macOS
    "start-win": "set NODE_ENV=production && node app.js"  // Windows
  }
}

跨平台推荐使用 cross-env：

npm install --save-dev cross-env

{
  "scripts": {
    "start": "cross-env NODE_ENV=production node app.js"
  }
}

实际案例

# 场景1: 开发时启动热重载服务器
npm run dev

# 场景2: 构建生产版本
npm run build

# 场景3: 运行单元测试并生成覆盖率报告
npm run test -- --coverage

# 场景4: 组合多个脚本（通过 && 或第三方如 npm-run-all）
{
  "scripts": {
    "check": "npm run lint && npm run test",
    "all": "npm-run-all --parallel lint test build"
  }
}

8. `npm test` / `npm start` – 常用脚本快捷方式

这两个命令是 npm run test 和 npm run start 的快捷方式。

`npm test`

运行测试脚本，通常用于 CI/CD 流程。

# 如果 package.json 中定义了 test 脚本
npm test

# 传递参数
npm test -- --verbose

# 如果未定义 test 脚本，执行 npm test 会报错
# 可以定义默认行为： "test": "echo \"Error: no test specified\" && exit 1"

`npm start`

启动应用程序。

npm start
# 通常对应 node server.js 或 next start 等

其他内置快捷脚本

npm stop：停止应用（如果有定义）
npm restart：执行 stop、restart、start（如果未定义 restart，则只执行 stop 和 start）
npm shrinkwrap：锁定依赖（独立命令）

实际案例：

# 场景1: 测试驱动开发
npm test -- --watch   # Jest 的监视模式

# 场景2: 部署后启动服务
npm start

# 场景3: 在 Dockerfile 中使用
CMD ["npm", "start"]

9. `npm ci` – 快速可重现安装

专门用于持续集成环境，基于 package-lock.json 进行安装，速度更快且保证一致性。

特点

必须存在 package-lock.json 或 npm-shrinkwrap.json
会先删除 node_modules，然后全新安装
严格按照 lock 文件安装，不修改 lock 文件
安装失败时不会写入 lock 文件
比 npm install 快 2~5 倍（跳过依赖解析）

基本用法

npm ci

常用选项

# 仅安装生产依赖
npm ci --only=production

# 仅安装开发依赖
npm ci --only=dev

# 静默模式
npm ci --quiet

实际案例

# 场景1: CI 流水线中（GitHub Actions, GitLab CI, Jenkins）
steps:
  - checkout
  - run: npm ci
  - run: npm test
  - run: npm run build

# 场景2: 本地确保依赖与 lock 文件一致
npm ci   # 如果 node_modules 已存在，会先删除再安装

# 场景3: 生产部署（避免开发依赖）
npm ci --only=production

注意事项

如果 package.json 和 package-lock.json 版本冲突，npm ci 会报错退出。
不要用 npm ci 来安装新包，它只用于安装已锁定的依赖。

10. `npm audit` – 安全审计与修复

扫描依赖树中的已知安全漏洞，并提供自动修复建议。

基础用法

# 扫描漏洞（输出报告）
npm audit

# 自动修复可修复的漏洞（升级到补丁版本）
npm audit fix

# 强制升级到最新版本（可能引入破坏性变更）
npm audit fix --force

# 只修复生产依赖的漏洞
npm audit fix --only=prod

# 以 JSON 格式输出（便于集成）
npm audit --json

审计报告示例

found 5 vulnerabilities (3 low, 2 moderate) in 123 scanned packages
  run `npm audit fix` to fix 2 of them.
  1 vulnerability requires semver-major dependency updates.
  2 vulnerabilities require manual review.

实际案例

# 场景1: 日常安全检查
npm audit

# 场景2: 自动修复非破坏性漏洞
npm audit fix

# 场景3: 处理 major 级别的漏洞（手动升级）
npm outdated
npm install major-package@latest
npm audit

# 场景4: CI 中阻断构建（如果存在高危漏洞）
npm audit --audit-level=high  # 可选值: low, moderate, high, critical
# 如果存在 high 或 critical 漏洞，命令退出码非 0

配置审计级别

# 设置仅当存在 critical 漏洞时才失败（默认 low）
npm audit --audit-level=critical

11. `npm dedupe` – 去重依赖

将依赖树中重复的包尽可能提升到顶层，减少 node_modules 体积。

基本用法

npm dedupe
# 或
npm ddp

原理

npm 会移动子依赖中的相同版本包到顶层 node_modules，消除冗余。

实际案例

# 项目安装了大量依赖后，可能有重复
npm install
npm dedupe   # 优化 node_modules 结构

示例

安装 A 和 B，两者都依赖 lodash@4.17.21，但一个在顶层，一个在子目录。执行 npm dedupe 后会合并为一个 lodash 在顶层。

12. `npm link` – 本地开发链接

用于在本地开发和测试自己的 npm 包时，将一个包“链接”到另一个项目中，避免重复发布。

步骤1: 在包目录中创建全局链接

cd ~/my-package
npm link   # 创建全局符号链接（指向当前目录）

步骤2: 在项目中使用链接

cd ~/my-project
npm link my-package   # 将全局链接的包引入到当前项目的 node_modules

取消链接

cd ~/my-project
npm unlink my-package   # 移除链接，恢复为普通包（如果有安装）

cd ~/my-package
npm unlink              # 删除全局链接

链接的替代方案（本地路径安装）

# 直接使用相对路径（无需全局链接）
npm install ../my-package
# 这会在 package.json 中写入："my-package": "file:../my-package"

实际案例

# 场景1: 开发一个 UI 组件库，在 demo 项目中实时测试
cd ~/projects/ui-lib
npm link

cd ~/projects/demo-app
npm link ui-lib
# 现在修改 ui-lib 的代码，demo-app 中会立即生效（如果是通过源文件引用）

# 场景2: 链接多个包相互依赖
cd ~/projects/core
npm link

cd ~/projects/plugin
npm link core   # plugin 依赖 core
npm link        # 同时 plugin 也建立全局链接

cd ~/projects/main-app
npm link core plugin

注意事项

npm link 会创建符号链接，注意 Windows 需管理员权限或开启开发模式。
链接可能导致版本解析问题，调试结束后最好用 npm unlink 并重新安装。

13. `npm config` – 配置管理

查看、设置、删除 npm 配置项。

基础用法

# 列出所有配置
npm config list

# 列出所有配置（包括默认值）
npm config list -l

# 获取某项配置
npm config get registry

# 设置配置
npm config set registry https://registry.npmmirror.com

# 删除配置
npm config delete registry

# 编辑用户配置文件（~/.npmrc）
npm config edit

常用配置项

配置项	说明	示例值
`registry`	包镜像源	`https://registry.npmmirror.com`
`proxy`	HTTP 代理	`http://proxy.company.com:8080`
`https-proxy`	HTTPS 代理	`http://proxy.company.com:8080`
`strict-ssl`	是否严格校验 SSL	`false`（内网自签名证书时）
`prefix`	全局安装路径	`~/.npm-global`
`cache`	缓存目录	`~/.npm-cache`
`init-author-name`	npm init 默认作者	`"张三"`
`init-license`	默认许可证	`MIT`
`save-prefix`	保存版本时的前缀	`^` 或 `~`
`audit-level`	审计失败等级	`high`

实际案例

# 场景1: 切换淘宝镜像
npm config set registry https://registry.npmmirror.com

# 场景2: 设置代理（公司内网）
npm config set proxy http://proxy.example.com:3128
npm config set https-proxy http://proxy.example.com:3128

# 场景3: 关闭 SSL 验证（不推荐，除非内网测试）
npm config set strict-ssl false

# 场景4: 设置全局安装路径
npm config set prefix ~/node-global
export PATH=~/node-global/bin:$PATH   # 添加到 shell 配置文件

# 场景5: 设置保存依赖时使用 ~ 而不是 ^
npm config set save-prefix "~"

# 场景6: 查看所有配置并过滤
npm config list | grep registry

# 场景7: 为特定项目覆盖配置（在项目根目录创建 .npmrc）
echo "registry=https://my-private-registry.com/" > .npmrc

14. `npm cache` – 缓存管理

管理 npm 下载的包缓存，可加速重复安装。

基本用法

# 查看缓存目录路径
npm config get cache

# 列出缓存中的包（不推荐直接操作）
ls ~/.npm/_cacache/

# 验证缓存数据的完整性和有效性
npm cache verify

# 清除所有缓存（强制）
npm cache clean --force

# 清除指定包的缓存（需要第三方工具）
# npm 本身不支持单个包清理，可删除 ~/.npm/_cacache/ 中对应条目

实际案例

# 场景1: 修复缓存损坏
npm cache verify
# 输出: Cache verified and compressed (Content verified: 1234, Content garbage-collected: 56)

# 场景2: 完全清空缓存（磁盘空间不足或诡异错误）
npm cache clean --force

# 场景3: 查看缓存大小
du -sh ~/.npm   # Linux/macOS
# Windows: 直接查看文件夹属性

缓存策略

npm 默认会缓存每个包的 tarball，再次安装时优先从缓存读取。
使用 --prefer-offline 优先从缓存读取，--offline 完全离线安装。

npm install --prefer-offline
npm install --offline   # 如果缓存缺失则失败

15. `npm doctor` – 环境诊断

检查本地 npm 环境是否正常，包括 Node.js 版本、npm 版本、网络、权限等。

基本用法

npm doctor

检查项

npm ping: 能否连接到 npm registry
npm -v: npm 版本是否过时
node -v: Node.js 版本是否过时
npm config get registry: registry 配置是否正常
Git 可用性
全局目录权限
缓存目录权限

输出示例

Check                               Value   Recommendation/Notes
npm ping                            ok
npm -v                              ok      current: v10.2.4, latest: v10.2.5 (minor)
node -v                             ok      current: v20.11.0, recommended: v20.11.0
npm config get registry             ok      using default registry (https://registry.npmjs.org/)
Git                                                 installed
Global bins                         ok      /usr/local/bin is in PATH.
Local node_modules                  ok      exists
Cache                               ok      cache path: /Users/me/.npm/_cacache

实际案例

# 当遇到奇怪的问题时，先跑一下医生
npm doctor

# 如果发现权限问题，可以修复
sudo chown -R $(whoami) ~/.npm

16. `npm exec` / `npx` – 执行包命令

运行 Node 包中的可执行文件，无需全局安装。

`npx` (npm 5.2+ 内置)

# 执行本地 node_modules/.bin 中的命令
npx eslint --init

# 执行远程包（临时下载并运行）
npx create-react-app my-app

# 执行特定版本
npx typescript@4.9.5 tsc --version

# 使用 --yes 跳过提示
npx --yes cowsay "Hello"

# 执行 GitHub gist 或 URL（危险，谨慎）
npx https://gist.github.com/example/script.js

`npm exec` (npm 7+)

# 基本等价于 npx
npm exec eslint --init

# 传递参数用 --
npm exec jest -- --coverage

实际案例

# 场景1: 不安装 TypeScript 全局，直接编译
npx tsc index.ts

# 场景2: 创建 Next.js 项目
npx create-next-app@latest my-next-app

# 场景3: 运行本地工具
npx webpack --config webpack.config.js

# 场景4: 使用 http-server 临时起一个服务器
npx http-server . -p 8080

# 场景5: 运行不同版本的 vite
npx vite@2 build
npx vite@3 build

常用选项

# 指定包管理器
npx --package=lodash --call "lodash.add(1,2)"

# 使用本地 node_modules 优先
npx --no-install eslint   # 如果本地没有，不会下载安装，直接报错

# 静默模式
npx --quiet some-command

17. `npm publish` / `npm unpublish` – 发布与撤销

将自己开发的包发布到 npm 注册表，或撤销已发布的版本。

发布前准备

注册账号：npm adduser
登录：npm login
确保包名未被占用（npm search <name>）
准备好 README.md、LICENSE 等

发布包

# 发布当前目录（版本号取自 package.json）
npm publish

# 发布带标签的版本（默认 latest）
npm publish --tag beta

# 发布到私有作用域（需要付费）
npm publish --access restricted   # 私有包
npm publish --access public       # 公开包（默认）

# 发布前打包测试
npm pack   # 生成 .tgz 文件，检查内容

撤销发布（限制）

# 24 小时内可以撤销（之后不能再撤）
npm unpublish my-package@1.0.0

# 撤销整个包（需要联系 npm 团队）
npm unpublish my-package --force   # 不推荐

弃用包（推荐替代撤销）

npm deprecate my-package@"<1.2.0" "This version has a security vulnerability, upgrade to 1.2.0"

实际案例

# 场景1: 首次发布一个工具库
cd my-lib
npm version patch   # 1.0.0 -> 1.0.1
npm publish

# 场景2: 发布 beta 版本供测试
npm version premajor --preid=beta   # 2.0.0-beta.0
npm publish --tag beta

# 场景3: 撤销错误的 1.0.0 版本（24h内）
npm unpublish my-lib@1.0.0

发布配置

在 package.json 中可以控制发布内容：

{
  "files": ["dist", "lib", "index.js"],
  "private": true,   // 设置为 true 则无法发布
  "publishConfig": {
    "registry": "https://my-private-registry.com/",
    "access": "public"
  }
}

18. `npm version` – 版本管理

升级 package.json 中的版本号，并自动创建 git 标签。

基本用法

# 查看当前版本
npm version

# 升级补丁版本（1.0.0 -> 1.0.1）
npm version patch

# 升级次要版本（1.0.0 -> 1.1.0）
npm version minor

# 升级主要版本（1.0.0 -> 2.0.0）
npm version major

# 预发布版本
npm version prepatch      # 1.0.0 -> 1.0.1-0
npm version preminor      # 1.0.0 -> 1.1.0-0
npm version premajor      # 1.0.0 -> 2.0.0-0
npm version prerelease    # 1.0.1-0 -> 1.0.1-1

# 自定义版本号
npm version 3.2.1

选项控制

# 不创建 git 标签
npm version patch --no-git-tag-version

# 不提交到 git（也不打标签）
npm version patch --no-commit-hooks --no-git-tag-version

# 强制执行（忽略工作区未提交变更）
npm version patch --force

实际案例

# 场景1: 修复 bug 后发布补丁
git add .
git commit -m "fix: correct typo"
npm version patch   # 自动增加版本，生成 git tag v1.0.1
git push --follow-tags
npm publish

# 场景2: 新功能发布次要版本
npm version minor -m "chore: release v%s"   # %s 会被替换为版本号
git push origin main --tags

# 场景3: 跳过 git 操作（比如在 CI 中）
npm version patch --no-git-tag-version

19. `npm deprecate` – 弃用包

为某个包的一个或多个版本添加弃用警告，当用户安装时会在控制台显示警告信息。

基本用法

npm deprecate <pkg>[@<version range>] <message>

# 示例：弃用整个包的所有版本
npm deprecate my-package "This package is no longer maintained"

# 弃用特定版本范围
npm deprecate my-package@"<1.2.0" "Please upgrade to 1.2.0 which fixes a critical bug"

# 弃用单个版本
npm deprecate my-package@1.0.0 "This version is broken"

实际案例

# 场景1: 发布新包时，通知用户旧版本不用了
npm deprecate old-lib@"0.x.x" "Version 1.0.0 is out with breaking changes"

# 场景2: 安全漏洞提醒
npm deprecate crypto-pkg@"<=2.3.0" "Vulnerable to CVE-2023-1234, upgrade to 2.3.1"

# 场景3: 取消弃用（重新发布新版本即可覆盖，弃用状态不会自动消失）
# 需要专门联系 npm 支持

查看弃用信息

npm view my-package
# 会在输出中显示 deprecated 字段

20. `npm view` – 查看包信息

查看 npm 仓库中包的元数据，无需安装。

基本用法

# 查看包的所有信息
npm view lodash

# 查看包的特定字段
npm view lodash version
npm view lodash dependencies
npm view lodash maintainers
npm view lodash homepage

# 查看包的所有可用版本
npm view lodash versions

# 查看指定版本信息
npm view lodash@4.17.20

# 查看包的最近更新日期
npm view lodash time.modified

# 以 JSON 输出
npm view lodash --json

实际案例

# 场景1: 快速查看包最新版本
npm view react version

# 场景2: 查看包依赖哪些其他包
npm view express dependencies

# 场景3: 查看包的许可证
npm view lodash license

# 场景4: 查看包的 README
npm view lodash readme

# 场景5: 检查包是否已被弃用
npm view some-package deprecated

21. `npm search` – 搜索包

在 npm 注册表中搜索包。

基本用法

npm search <keyword>

# 示例：搜索 webpack 相关插件
npm search webpack plugin

# 限制结果数量
npm search --searchlimit 20 express

# 不显示描述（只显示包名）
npm search --no-describe lodash

输出格式

NAME                      DESCRIPTION          AUTHOR          DATE        VERSION  KEYWORDS
express                   Fast, unopinionated…  tjholowaychuk   2024-01-15  4.18.2   web framework

实际案例

# 寻找日期处理库
npm search date

# 搜索特定作用域下的包
npm search @babel/core

# 搜索带有特定关键词的包
npm search "react hooks"

替代方案

官方网站 npmjs.com 提供更强大的搜索功能。

22. `npm whoami` / `npm adduser` / `npm login` – 身份认证

管理 npm 注册表的用户身份。

`npm whoami`

显示当前登录的用户名。

npm whoami
# 输出：zhangsan
# 如果未登录，输出：npm ERR! code E401

`npm adduser`

创建新用户（或登录，但通常用 login）。

npm adduser
# 提示输入用户名、密码、邮箱

`npm login`

登录到 npm 注册表。

npm login
# 交互式输入

使用 Token 登录（CI 环境）

# 1. 在 https://npmjs.com 生成 Access Token
# 2. 在环境变量或 .npmrc 中设置
echo "//registry.npmjs.org/:_authToken=<your-token>" > ~/.npmrc

# 或者
npm config set //registry.npmjs.org/:_authToken <token>

实际案例

# 场景1: 首次发布前登录
npm login
# 输入用户名、密码、邮箱（邮箱会收到一次性验证码）
npm whoami  # 确认

# 场景2: CI 中使用环境变量
export NPM_TOKEN=00000000-0000-0000-0000-000000000000
npm config set //registry.npmjs.org/:_authToken ${NPM_TOKEN}

# 场景3: 使用自动化 token（粒度更细）
# 在 npm 网站创建 Automation token，用于 CI 发布

23. `npm logout` – 退出登录

清除本地存储的 npm 认证信息。

npm logout

注意

不会影响已发布的包。
仅删除本地 .npmrc 中的认证 token。

24. `npm pack` – 打包为 tarball

将当前包打包成 .tgz 文件，模拟发布时的内容，用于检查或离线安装。

基本用法

npm pack
# 生成 my-package-1.0.0.tgz

# 不压缩（显示打包内容列表）
npm pack --dry-run

# 指定输出目录
npm pack --pack-destination ./artifacts

实际案例

# 场景1: 检查发布时会包含哪些文件
npm pack --dry-run

# 场景2: 生成 tarball 发给同事测试安装
npm pack
scp my-package-1.0.0.tgz user@server:/tmp/
# 在服务器上安装：npm install /tmp/my-package-1.0.0.tgz

# 场景3: 本地测试安装
cd ../test-project
npm install ../my-lib/my-lib-1.0.0.tgz

25. `npm rebuild` – 重新编译

重新编译所有原生（C++）模块。当 Node.js 版本更换或依赖缺失二进制文件时使用。

基本用法

# 重新编译所有原生模块
npm rebuild

# 只重新编译特定包
npm rebuild bcrypt

# 强制重新编译
npm rebuild --force

实际案例

# 场景1: 切换 Node.js 版本后（nvm use 16 -> 18）
npm rebuild

# 场景2: 某些模块报错 "could not be resolved"
npm rebuild node-sass

# 场景3: 删除 node_modules 重装后，原生模块可能不需要 rebuild，因为 npm install 会编译
# 但有时需要显式执行

26. `npm prune` – 清理多余包

删除 node_modules 中不在 package.json 依赖列表中的包。

基本用法

# 删除多余的包
npm prune

# 仅删除生产依赖中多余的包（忽略 devDependencies）
npm prune --production

# 仅删除开发依赖中多余的包
npm prune --dev

实际案例

# 场景1: 手动删除了 package.json 中的包，但 node_modules 还有残留
npm uninstall lodash   # 通常会自动移除，但万一没删干净
npm prune              # 彻底清理

# 场景2: 生产环境部署前清理开发依赖
npm install --only=production
# 或者先正常安装，再 prune
npm prune --production

与 `npm ci` 的区别

npm ci 会完全删除 node_modules 并严格按照 lock 重装。
npm prune 只删除多余包，不会新增或更新。

27. `npm docs` / `npm repo` – 快速打开文档/仓库

在浏览器中打开包的文档或代码仓库。

基本用法

# 打开包的文档主页（通常为 README）
npm docs express
# 等价于：npm home express

# 打开包的 GitHub 仓库
npm repo express

实际案例

# 场景1: 想查看 lodash 的 API 文档
npm docs lodash

# 场景2: 想给 react 提 issue 或看源码
npm repo react   # 打开 GitHub

28. `npm bugs` – 打开 issues 页面

快速打开包的 bug 跟踪系统（通常是 GitHub issues）。

npm bugs express
# 会打开 https://github.com/expressjs/express/issues

29. `npm explore` – 进入包目录交互

进入已安装包的目录，并启动一个 shell 子进程，方便调试。

基本用法

# 进入 lodash 包目录并打开 shell
npm explore lodash

# 执行单条命令而不进入交互
npm explore lodash -- npm run build

实际案例

# 场景1: 查看包的内部文件结构
npm explore webpack
ls -la
exit

# 场景2: 执行包内部的脚本
npm explore eslint -- node bin/eslint.js --version

30. `npm diff` – 对比包版本差异

对比当前安装的包与另一个版本之间的文件差异。

基本用法

# 对比当前包与最新版本
npm diff lodash

# 对比两个指定版本
npm diff lodash@4.17.20 lodash@4.17.21

# 对比当前项目与上一个版本（需先有 package.json 版本历史）
npm diff

实际案例

# 查看 axios 从 1.5.0 到 1.6.0 改了哪些文件
npm diff axios@1.5.0 axios@1.6.0

附录：npm 命令速查表（实战高频）

命令	常用场景
`npm init -y`	快速创建项目
`npm i lodash`	安装生产依赖
`npm i -D jest`	安装开发依赖
`npm i -g nodemon`	全局安装工具
`npm un lodash`	卸载依赖
`npm up`	更新小版本
`npm outdated`	查看过期依赖
`npm ls --depth=0`	查看直接依赖
`npm run dev`	运行开发脚本
`npm test`	运行测试
`npm ci`	CI 流水线安装
`npm audit fix`	修复安全漏洞
`npx create-react-app .`	创建项目脚手架
`npm link`	本地调试库
`npm config set registry ...`	换镜像源
`npm publish`	发布包
`npm version patch`	升级版本号
`npm view react version`	查最新版本
`npm cache clean --force`	清缓存

结束语：掌握这些命令，你已经可以应对 95% 的 npm 使用场景。实践中遇到不熟悉的命令，随时用 npm help <command> 查看官方文档。Happy coding! 🚀

npm 核心命令实战（超详细版）