npm使用手册

发表于 更新于 分类于 ， ， 置顶 精品
阅读次数： 本文字数： 3.6k 阅读时长 ≈ 13 分钟

摘要

  • 本文介绍如何使用npm

  • npm版本10.5.0

npm简介

  • npm（Node Package Manager）是 Node.js 的包管理工具，也是 JavaScript 编程社区中最常用的管理和分享代码的工具。

  • 它允许开发者轻松地安装、共享、和管理在项目中使用的 JavaScript 包。

  • npm 分为两个主要部分：命令行工具（CLI）和 npm 注册表。

  • 命令行工具（CLI）：用于与注册表进行交互，安装和管理项目中的依赖。

  • npm 注册表：一个在线的数据库，存储了数百万个开源的 Node.js 包，开发者可以在自己的项目中使用这些包。

npm 的安装与配置

  • npm 通常与 Node.js 一起安装，因此安装 Node.js 会自动安装 npm。

  • 从 Node.js 官网下载并安装 Node.js。

  • 跟随Node.js 官网–Download的提示完成 Node.js 的安装，

  • 现在官方更推荐使用nvm的方式进行安装，当然你也可以选择对应系统的二进制包进行安装（此种方法要将node的bin目录配置到PATH环境变量），node.js安装完成后，npm 也会一起安装。

  • 打开命令行或终端工具，输入以下命令来验证是否成功安装

1
2
npm -v
node -v

npm 常用命令

npm init：初始化项目

  • npm init命令用于初始化一个新的 Node.js 项目，生成一个package.json文件，其中包含项目的元数据和配置。

1
2
3
mkdir my-project
cd my-project
npm init

  • 执行该命令后，会按照提示输入一些项目相关的信息，如名称、版本、描述等。也可以使用 npm init -y 跳过提示，生成一个默认的package.json文件。

npm create：基于模板创建项目

  • npm create命令用于基于模板创建一个新的 Node.js 项目，比如我们创建一个基于Vue的Web项目，可以执行以下命令：

1
npm create vue@latest

npm install：安装依赖包

  • npm install命令用于安装项目中所需的依赖包，比如在package.json文件中指定了依赖包，可以执行以下命令：

1
npm install

  • 安装完成后，会在node_modules目录下生成依赖包，并更新package-lock.json文件。

  • 安装指定依赖包，默认安装最新版，自动将依赖包添加到 package.json 的 “dependencies” 部分。

1
npm install express

  • 如果需要安装特定的版本，可以执行以下命令：

1
npm install express@4.17.1

  • 安装开发依赖包，安装并写入package.json的"devDependencies"中

1
2
3
npm install express -D
# 等价于
npm install express --save-dev

  • 安装全局依赖包

1
2
3
4
5
6
7
# 全局安装的包会被安装到全局的node_modules目录下，不会被安装到项目目录下，也不会出现在package.json中
npm install express -g
# 等价于
npm install express --global

# 全局node_modules目录路径查看
npm root -g

  • 从本地安装依赖包

1
2
# 从本地安装
npm install ./path/to/local_project

  • 从远程Git仓库安装依赖包

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
# 安装公共项目：
# npm install https://github.com/user_name/node_project
npm install https://github.com/trentm/json.git
# 缩写，如果是gitlab仓库，则需要使用gitlab前缀，推荐使用上面的完整语义版本
npm install github:trentm/json

# 安装特定提交：
# npm install https://github.com/user_name/node_project#commit
npm install https://github.com/trentm/json.git\#6912b25272312d0f13ad32e98ebc1b4deb6334cc
# 安装特定分支：
# npm install https://github.com/user_name/node_project#branchName
npm install https://github.com/trentm/json.git\#streaming
# 通过标签安装：
# npm install https://github.com/user_name/node_project#tag
npm install https://github.com/trentm/json.git\#10.0.0
# 安装特定版本：
# npm install https://github.com/user_name/node_project#version
npm install https://github.com/trentm/json.git\#10.0.0
# 完整的语义版本：
npm install https://github.com/trentm/json.git\#semver:v10.0.0

# 使用git的ssh repo link 安装私有库：后面同样可以接 commit、branchName、tag、version等
# npm install git+ssh://git@github.com:user_name/node_project.git
npm install git+ssh://git@github.com/trentm/json.git

npm update：更新依赖包

  • npm update命令用于更新项目中的依赖包，比如要更新express依赖包到最新版本，可以执行以下命令：

1
2
3
4
5
6
# 更新生产环境依赖包
npm update express
# 更新开发环境依赖包
npm update express -D
# 全局更新
npm update express -g

  • 修改了package.json文件，并希望更新依赖包，可以执行以下命令：

1
2
# #为了避免不必要的麻烦，可以先删除项目中的node_modules文件夹在执行，此时和 npm install 一样
npm update

npm outdate：检查哪些包可以升级

  • npm outdate命令用于检查哪些包可以升级

1
2
3
4
5
6
7
# 检查当前项目下哪些包可以升级
npm outdate
# 检查指定包
npm outdated express
# 检查全局模块
npm outdate -g
npm outdated -g express

npm-upgrade：判断package.json哪些包需要升级

  • 安装

1
npm install -g npm-upgrade

  • 使用

1
2
3
4
# 判断package.json哪些包需要升级，用户确认后会自动更新package.json文件，此时只是更新文件，并没有真正升级
npm-upgrade
# 基于package.json中的配置进行升级，可以先删除node_modules再执行，此时和 npm install 一样
npm update

npm list：列出依赖包

  • npm list命令用于列出项目中的依赖包，比如要列出当前项目下的依赖包，可以执行以下命令：

1
2
3
4
5
6
7
8
9
# 此时列出的是package.json中的dependencies依赖包
npm list
# 列出开发依赖包，此时会列出package.json中的devDependencies和dependencies依赖包
npm list -D
# 列出指定包
npm list express
# 列出全局模块
npm list -g
npm list -g express

npm uninstall：卸载依赖包

  • npm uninstall命令用于卸载项目中的依赖包，比如要卸载express依赖包，可以执行以下命令：

1
2
3
npm uninstall express
# 删除全局模块
npm uninstall -g express

npm search：搜索依赖包

  • npm search命令用于搜索依赖包，比如要搜索express依赖包，可以执行以下命令：

1
npm search express

  • 可以使用正则表达式搜索依赖包，比如要搜索以express开头的依赖包，可以执行以下命令：

1
npm search /^express/

npm view == npm info：查看包信息

  • npm view命令用于查看包的信息，比如要查看express依赖包的信息，可以执行以下命令：

1
2
3
npm view express
# 或者，view与info命令可以互换使用
npm info express

  • npm view命令还可以查看包的所有版本信息，比如要查看express依赖包的所有版本信息，可以执行以下命令：

1
2
# 此时我们从结果中选择一个版本进行安装即可
npm view express versions

npm home：打开包的主页

  • 打开某个 npm 包的主页（通常是 GitHub 主页或 npm 页面）。

1
npm home express

npm 镜像源

  • npm 默认使用官方的镜像源，但是官方的镜像源速度很慢，我们可以使用第三方的镜像源来加速下载。

1
2
3
4
5
6
7
8
npm 官方原始镜像网址是：https://registry.npmjs.org/
淘宝 NPM 镜像：http://registry.npmmirror.com
阿里云 NPM 镜像：https://npm.aliyun.com
腾讯云 NPM 镜像：https://mirrors.cloud.tencent.com/npm/
华为云 NPM 镜像：https://mirrors.huaweicloud.com/repository/npm/
网易 NPM 镜像：https://mirrors.163.com/npm/
中国科学技术大学开源镜像站：http://mirrors.ustc.edu.cn/
清华大学开源镜像站：https://mirrors.tuna.tsinghua.edu.cn/

  • 可以通过以下命令来查看当前使用的镜像源：

1
npm config get registry

  • 可以通过以下命令来设置镜像源：

1
npm config set registry https://registry.npmmirror.com

  • 可以通过以下命令来删除用户配置的镜像源，删除后恢复为默认镜像源：

1
npm config delete registry

npm 配置

  • 可以通过以下命令来查看npm的配置信息：

1
2
3
4
5
6
# 查看全局配置信息，只显示用户自定义的配置信息
npm config list
# 查看全局配置信息，显示所有配置信息及其默认缺省值
npm config ls -l
# json 格式 显示全部配置信息
npm config list --json

  • 默认全局配置在当前用户HOME目录下的.npmrc文件中，可以通过以下命令来查看全局配置信息：

1
2
cat ~/.npmrc
cat ~/.npmrc | grep registry

  • 在项目根目录创建一个.npmrc 文件可以为该项目单独设置 npm 配置。

  • npm config 允许你控制 npm 的行为，包括 安装目录、代理、日志级别、依赖管理 等。

  • 你可以使用 npm config get <key> 查看值，npm config set <key> <value> 进行修改，npm config delete <key> 删除设置。

  • npm常用配置

配置项 作用 默认值
prefix 设置 npm 全局安装的路径（npm install -g 影响的目录） 环境变量 NODE_HOME 或 /usr/local（系统）
cache npm 的缓存目录 ~/.npm
registry 指定 npm 的包管理仓库地址（如官方、淘宝镜像） https://registry.npmjs.org/
strict-ssl 是否强制使用 HTTPS 进行 npm 操作 true
proxy 配置 HTTP 代理 null
https-proxy 配置 HTTPS 代理 null
init-author-name 设置 package.json 默认作者名称 “”
init-author-email 设置 package.json 默认作者邮箱 “”
init-author-url 设置 package.json 默认作者网站 “”
init-license 设置 package.json 默认许可证 “ISC”
init-version package.json 默认版本号 “1.0.0”
save-exact true 时，安装依赖时不使用 ^ 或 ~，直接锁定版本 false
engine-strict 是否强制匹配 package.json 的 engines 字段 false
loglevel 设置日志输出级别（silent, error, warn, notice, info, verbose, silly） notice
fund 是否显示 package 的资金支持信息 true
audit 是否启用安全审计 true

npm config save-exact

  • 推荐配置为 true，避免因为版本更新导致依赖包版本不匹配

1
npm config set save-exact true

npm config loglevel

  • loglevel 可选值

级别 说明 适用场景
silent 不输出任何日志（除非发生错误） 适用于 CI/CD 需要最少日志的环境
error 仅显示错误信息 只关心 npm 运行是否出错
warn 显示警告和错误 发现潜在问题但不影响使用
notice (默认) 显示关键信息、警告和错误 npm 默认值，适合大多数场景
http 记录 HTTP 请求的详细信息 用于调试 npm 下载速度问题
info 显示一般信息、依赖安装情况等 适用于一般开发者调试
verbose 详细的调试信息 适用于深入分析 npm 运行情况
silly 最详细的日志，包含所有调试信息 适用于 npm 开发者或极端调试需求

  • 设置方法

1
npm config set loglevel verbose

  • 临时使用

1
2
3
4
5
6
7
8
9
10
npm --loglevel verbose install
# 或者
npm -dd install

#  支持快捷方式的值：
# • -s, --silent: --loglevel silent
# • -q, --quiet: --loglevel warn
# • -d: --loglevel info
# • -dd, --verbose: --loglevel verbose
# • -ddd: --loglevel silly

npm config timing

  • timing 是 npm 的一个 日志输出配置项，用于控制是否在命令执行时显示详细的时间信息，默认值为 false。

  • 当 timing 设为 true 时，npm 会在命令执行结束后 打印详细的时间统计信息，包括：

    • 每个子任务的执行时间（如解析 package.json、解析 node_modules、下载依赖等）
    • 网络请求的耗时
    • 依赖解析和安装的耗时
    • 整体执行的时间开销

  • 这对分析 npm 性能、优化依赖安装速度非常有用，特别是在大项目或 CI/CD 环境中。

  • 启用 timing

1
npm config set timing true

  • 临时启用

1
npm --timing install

  • 适用场景

    • 分析 npm 命令执行时间，优化构建速度
    • CI/CD 环境中排查 npm 安装变慢的原因
    • 排查 npm 依赖解析、安装或下载过程的性能瓶颈

  • 一般日常开发：日志会变长，可能影响可读性，所以再没有遇到问题时不建议开启

npm、pnpm、yarn 之间的联系和区别

  • 这三者都是 JavaScript 生态中的包管理工具，主要用于安装、管理和运行 Node.js 项目的依赖。它们的关系如下：

    • npm（Node Package Manager）是 Node.js 官方自带的包管理工具。
    • yarn（Yet Another Resource Negotiator）是 Facebook 开发的替代 npm 的工具，提供更快、更安全的依赖管理。
    • pnpm（Performant npm）是一个更高效的 npm 替代品，使用硬链接和去重机制来减少磁盘占用并加快安装速度。

  • npm、pnpm、yarn 的主要区别

特性 npm yarn pnpm
默认包管理方式 直接安装到 node_modules/ 直接安装到 node_modules/ 使用 硬链接 + 共享依赖，占用更少磁盘
安装速度 5+ 版本后速度较快，但依赖解析仍有性能问题 速度较快，支持并行下载 最快，去重能力强
磁盘占用 较大（每个项目都会存一份完整的依赖） 较大（和 npm 类似） 最小（共享全局缓存，多个项目共用依赖）
锁文件 package-lock.json yarn.lock pnpm-lock.yaml
并发安装 支持（npm 5+ 优化） 支持（更快） 支持（最优化）
全局缓存 支持（但项目仍会存副本） 支持（仍会拷贝到 node_modules/） 强制启用（多个项目共用依赖，节省空间）
monorepo（多包管理） 需要手动配置 支持 Workspaces 原生支持 Workspaces（最强大）
命令兼容性 标准 兼容 npm，部分不同 兼容 npm，大部分命令相同
自动修复 package.json 是 是 是
生态兼容性 官方标准，兼容性最好 兼容 npm，但部分特性不同 兼容 npm，但采用不同的依赖管理方式

  • 常见命令对比

任务 npm yarn pnpm
初始化项目 npm init yarn init pnpm init
安装依赖 npm install yarn install pnpm install
安装特定依赖 npm install lodash yarn add lodash pnpm add lodash
安装开发依赖 npm install lodash -D yarn add lodash -D pnpm add lodash -D
删除依赖 npm uninstall lodash yarn remove lodash pnpm remove lodash
更新依赖 npm update lodash yarn upgrade lodash pnpm update lodash
全局安装 npm install -g serve yarn global add serve pnpm add -g serve
运行脚本 npm run dev yarn dev pnpm dev

  • 什么时候使用 npm、yarn、pnpm？

    • ✅ 使用 pnpm（推荐）：
      1.你希望减少磁盘占用、加快安装速度
      2.你正在开发 monorepo（多包）项目
      3.你希望更高效地管理依赖

    • ✅ 使用 yarn：
      1.你希望更快的安装速度，但又不想改变 npm 传统结构
      2.你的团队习惯使用 yarn.lock 文件
      3.你在用 React Native（官方推荐 yarn）

    • ✅ 使用 npm（适合简单项目）：
      1.你希望使用 Node.js 官方的默认工具
      2.你不想安装额外的包管理工具
      3.你在开发小型项目，不需要 workspaces