NPM install命令

前几篇教程我们认识了 package.json 和版本号，但项目里的依赖到底怎么装到电脑上？

npm install 是 NPM 最核心、最常用的命令。它看似简单，但功能非常强大，参数也十分丰富。

npm install 主要用于：

• 安装项目依赖
• 下载指定包
• 更新依赖
• 生成或更新 node_modules 目录
• 维护 package.json 与 package-lock.json 的一致性

执行时，npm 会从默认的 npm 注册表（https://registry.npmjs.org/）下载依赖包，并根据依赖树构建本地的 node_modules 目录。

语法

npm install [<package-spec> ...]

aliases: add, i, in, ins, inst, insta, instal, isnt, isnta, isntal, isntall

npm install 有一个常用的简写形式——npm i。两者完全等价，你可以根据自己的习惯选择使用。

无参数安装：安装所有依赖

在项目根目录下直接运行：

npm install
# 或简写
npm i

这会根据当前目录下的 package.json 文件，安装其中声明的所有依赖（包括 dependencies 和 devDependencies）。安装后的包会存放在项目本地的 node_modules 文件夹中。

安装单个包

npm install <package-name>
# 例如：安装 express
npm install express

这会安装指定包的最新版本。

安装指定版本的包

npm install <package-name>@<version>
# 例如：安装 lodash 的 4.17.21 版本
npm install lodash@4.17.21

核心参数

--save / -S：生产依赖

作用：将包添加到 package.json 的 dependencies 字段（生产环境依赖）。

默认行为：从 npm v5 开始，npm install 默认就等同于 --save，因此你可以省略该参数。

使用场景：安装运行时必需的库，如 react、axios、lodash 等。

npm install axios
# 等价于
npm install --save axios
# 等价于
npm install -S axios

--save-dev / -D：开发依赖

作用：将包添加到 package.json 的 devDependencies 字段（开发环境依赖）。

使用场景：安装仅在开发阶段使用的工具，如构建工具（webpack、vite）、测试框架（jest、cypress）、代码检查工具（eslint、prettier）等。

npm install webpack --save-dev
# 或简写
npm install webpack -D

注意：生产环境执行 npm install --production 时会跳过 devDependencies 中的包。

--global / -g：全局安装

作用：将包安装到系统全局，而非当前项目。

使用场景：安装命令行工具（CLI），如 typescript、create-react-app 等。

npm install -g typescript

安装后，你就可以在终端中直接使用 tsc 命令了。

注意：

• 全局安装的包不会记录在 package.json 中
• 不建议在项目依赖中使用全局包，这会破坏项目的可复现性
• 全局安装路径可通过 npm root -g 查看

--production：仅安装生产依赖

作用：只安装 dependencies 中的包，跳过 devDependencies。

使用场景：部署阶段（如 Docker 构建、CI/CD 环境）。

npm install --production

--no-save：临时安装不写入 package.json

作用：安装包但不写入 package.json。

使用场景：快速测试某个包，或本地调试时不想污染依赖配置。

npm install lodash --no-save

安装后包仅存在于 node_modules，下次运行 npm install 不会自动恢复。

--save-exact / -E：精确版本锁定

作用：安装时使用精确版本号，不添加 ^ 或 ~ 前缀。

默认行为：npm 默认使用 ^1.2.3 格式（允许兼容更新）。

使用场景：需要严格锁定版本，避免自动升级引入破坏性变更（适用于企业级项目）。

npm install lodash --save-exact
# package.json 中记录为："lodash": "4.17.21"

--legacy-peer-deps：忽略同伴依赖冲突

作用：忽略 peerDependencies（同伴依赖）的冲突。

使用场景：旧项目或包依赖冲突较多的情况（尤其在 npm 7+ 之后）。

npm install --legacy-peer-deps

--force / -f：强制重新安装

作用：强制重新下载依赖，即使本地已有缓存。

使用场景：解决缓存损坏、版本不一致等问题。

npm install --force

--dry-run：模拟安装

作用：仅模拟安装过程，不实际下载或修改文件。

使用场景：调试、检查依赖解析过程。

npm install --dry-run

--prefer-offline 与 --prefer-online

作用：控制是否优先使用本地缓存。

• --prefer-offline：优先使用本地缓存，网络不通时更快
• --prefer-online：每次都从远程检查更新

npm install --prefer-offline

--omit：选择性省略依赖（npm 7+）

作用：选择性地省略某类依赖。

# 省略开发依赖（等价于 --production）
npm install --omit=dev

# 省略可选依赖
npm install --omit=optional

参数速查表

参数	简写	作用	使用场景
--save	-S	添加到 dependencies（默认行为）	生产依赖
--save-dev	-D	添加到 devDependencies	开发依赖
--global	-g	全局安装	CLI 工具
--production	-	只装生产依赖	部署环境
--no-save	-	不写入 package.json	临时测试
--save-exact	-E	精确版本锁定	企业项目
--legacy-peer-deps	-	忽略同伴依赖冲突	旧项目兼容
--force	-f	强制重装	缓存修复
--dry-run	-	模拟安装	调试检查
--prefer-offline	-	优先使用缓存	离线环境