npm install

安装包

概要

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

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

描述

这个命令安装一个包以及它所依赖的任何包。如果包有一个 package-lock，或一个 npm shrinkwrap 文件，或一个 yarn lock 文件，依赖项的安装将由该文件驱动，遵循以下优先顺序:

• npm-shrinkwrap.json
• package-lock.json
• yarn.lock

详见 package-lock.json 和 npm shrinkwrap.

一个 package 是：

• a) 包含 package.json 文件描述的程序的文件夹
• b) 一个 gzip 压缩包文件，包含 (a)
• c) 解析为 (b) 的url
• d) 在注册中心（详见 registry）上发布的 <name>@<version>，带有 (c)
• e) 指向 (d) 的 <name>@<tag>（详见 npm dist-tag）
• f) 有 "latest" 标签的 <name> 满足 (e)
• g) 解析为 (a) 的 <git remote url>

即使你从来没有发布过你的包，如果你只是想写一个节点程序 (a)，或者如果你想在打包成 tarball 之后在其他地方轻松安装它 (b)，你仍然可以使用 npm 获得很多好处。

• npm install（在包目录中，没有参数）

将依赖项安装到本地 node_modules 文件夹。

在全局模式（ 即在命令后加上 -g 或 --global ）中，它将当前包上下文（ 即当前工作目录 ）安装为全局包。

默认情况下，npm install 将安装 package.json 中列出的所有依赖项模块。

有了 --production 标志 ( 或当 NODE_ENV 环境变量设置为 production 时 )， npm 将不会安装列出在 devDependencies 中的模块。当 NODE_ENV 环境变量设置为 production 时，要安装 dependencies 和 devDependencies 中列出的所有模块，你可以使用 --production=false。

注意

在向项目添加依赖项时，--production 标志没有特别的含义。

• npm install <folder>：

如果 <folder> 位于项目的根目录中，那么它的依赖项将被安装，并可能像其他类型的依赖项一样被提升到顶级 node_modules。如果 <folder> 位于项目的根目录之外，npm 不会将包依赖项安装在 <folder> 目录中，但它会创建一个指向 <folder> 的符号链接。

注意

如果您想从注册中心安装目录的内容（如包）而不是创建链接，则需要使用 --install-links 选项。

例子

npm install ../../other-package --install-links
npm install ./sub-package

• npm install <tarball file>：

安装位于文件系统上的包。注意:如果你只是想把一个 dev 目录链接到你的 npm 根目录，你可以使用 npm link 更容易地做到这一点。

压缩包要求： 1）文件名必须使用 .tar、.tar.gz 或 .tgz 作为扩展名。 2）包内容应该位于 tarball (通常被称为 package/) 中的子文件夹中。 3）包必须包含一个具有 name 和 version 属性的 package.json 文件。

例子：

npm install ./package.tgz

• npm install <tarball url>：

获取 tarball url，然后安装它。为了区分这个和其他选项，参数必须以 "http://" 或 "https://" 开头。

例子：

npm install https://github.com/indexzero/forever/tarball/v0.5.6

• npm install [<@scope>/]<name>：

进行 <name>@<tag> 安装，其中 <tag> 是 "tag" 配置。(详见 config，该配置的默认值为 latest)

在大多数情况下，这将安装在 npm 注册表中标记为 latest 的模块版本。

例子：

npm install sax

npm install 默认将任何指定的包保存到 dependencies 中。另外，你可以通过一些附加标志来控制它们的保存位置和方式：

1）-P, --save-prod: 包会出现在你的 dependencies 中. 这是默认设置，除非 -D 或 -O 存在。

2）-D, --save-dev: 包会出现在你的 devDependencies 中。

3）-O, --save-optional: 包会出现在你的 optionalDependencies 中。

4）--no-save: 防止保存到 dependencies。

当使用上述任何选项将依赖项保存到 package.json 时，还有两个额外的可选标志：

1）-E, --save-exact: 保存的依赖项将使用精确的版本进行配置，而不是使用 npm 的默认 semver 范围运算符。

2）-B, --save-bundle: 保存的依赖项也将添加到您的 bundleDependencies 列表中。

此外，如果您有 npm-shrinkwrap.json 或 package-lock.json 那么它也会被更新。

<scope> 是可选的。包将从与指定范围关联的注册中心中下载。如果注册中心没有与给定范围关联，则假定默认的注册中心。详见 scope。

注意

如果你的范围名称中没有包含 @-symbol，npm 会将其解释为 GitHub 存储库，见下文。范围名称后还必须跟一个斜杠。

例子

npm install sax
npm install githubname/reponame
npm install @myorg/privatepackage
npm install node-tap --save-dev
npm install dtrace-provider --save-optional
npm install readable-stream --save-exact
npm install ansi-regex --save-bundle

如果当前工作目录中有一个名为 <name> 的文件或文件夹，那么它将尝试安装该文件或文件夹，并且只有在包无效时才尝试通过名称获取包。

• npm install <alias>@npm:<name>：

在自定义别名下安装包。允许并排同名包的多个版本，更方便地导入具有其他长包的名称，并使用 git forks 替换或分叉的 npm 包作为替换。别名仅适用于您的项目，不会重命名传递依赖项中的包。别名应遵循 validate-npm-package-name。

例子：

npm install my-react@npm:react
npm install jquery2@npm:jquery@2
npm install jquery3@npm:jquery@3
npm install npa@npm:npm-package-arg

• npm install [<@scope>/]<name>@<tag>：

安装指定标签引用的包版本。如果该包的注册中心数据中不存在该标记，则此操作将失败。

例子：

npm install sax@latest
npm install @myorg/mypackage@latest

• npm install [<@scope>/]<name>@<version>：

安装指定版本的软件包。如果版本没有发布到注册中心，则此操作将失败。

例子：

npm install sax@0.1.1 
npm install @myorg/privatepackage@1.5.0 

• npm install [<@scope>/]<name>@<version range>：

安装与指定版本范围匹配的软件包版本。这将遵循在 package.json 中描述的解析依赖关系的相同规则。

请注意，大多数版本范围必须放在引号中，以便您的 shell 将其视为单个参数。

例子：

npm install sax@ ">=0.1.0 <0.2.0" 
npm install @myorg/privatepackage@ "16 - 17" 

• npm install <git remote url>：

从托管的 git 提供程序安装包，用 git 克隆它。对于完整的 git 远程 url，只会尝试该 url。

<protocol>://[<user>[:<password>]@]<hostname>[:<port>][:][/]<path>[#<commit-ish> | #semver:<semver>]

<protocol> 是 git, git+ssh, git+http, git+https，或者 git+file 中的一个。

如果 #<commit-ish> 提供，它将用于准确克隆该提交。如果 commit-ish 的格式为 #semver:<semver>,<semver> 可以是任何有效的 semver 范围或确切版本，npm 将在远程存储库中查找与该范围匹配的任何标签或引用，就像它查找注册表依赖项一样。如果两者均未指定 #<commit-ish> 或未 #semver:<semver> 指定，则使用存储库的默认分支。

如果存储库使用子模块，这些子模块也将被克隆。

如果正在安装的包包含一个 prepare 脚本，则在打包和安装包之前，将安装它 dependencies，devDependencies 并且运行准备脚本。

以下 git 环境变量被 npm 识别，并在运行 git 时添加到环境中：

• GIT_ASKPASS

• GIT_EXEC_PATH

• GIT_PROXY_COMMAND

• GIT_SSH

• GIT_SSH_COMMAND

• GIT_SSL_CAINFO

• GIT_SSL_NO_VERIFY

有关详细信息，请参阅 git 手册页。

例子：

npm install git+ssh://git@github.com:npm/cli.git#v1.0.27
npm install git+ssh://git@github.com:npm/cli#pull/273
npm install git+ssh://git@github.com:npm/cli#semver:^5.0
npm install git+https://isaacs@github.com/npm/cli.git
npm install git://github.com/npm/cli.git#v1.0.27

GIT_SSH_COMMAND='ssh -i ~/.ssh/custom_ident' npm install git+ssh://git@github.com:npm/cli.git

• npm install <githubname>/<githubrepo>[#<commit-ish>]：
• npm install github:<githubname>/<githubrepo>[#<commit-ish>]：

在 https://github.com/githubname/githubrepo 安装该包，尝试使用 git 克隆它。

如果 #<commit-ish> 提供，它将用于准确克隆该提交。如果 commit-ish 的格式为 #semver:<semver>,<semver> 可以是任何有效的 semver 范围或确切版本，npm 将在远程存储库中查找与该范围匹配的任何标签或引用，就像它查找注册中心依赖项一样。如果没有指定 #<commit-ish> 或 #semver:<semver>，则使用默认分支。

与常规 git 依赖一样，如果包在安装之前有一个 prepare 脚本，dependencies 和 devDependencies 将被安装。

例子：

npm install mygithubuser/myproject
npm install github:mygithubuser/myproject

• npm install gist:[<githubname>/]<gistID>[#<commit-ish>|#semver:<semver>]：

在 https://gist.github.com/gistID 安装该包，尝试使用 git 克隆它。与 gist 关联的 GitHub 用户名是可选的，不会保存在 package.json 中。

与常规 git 依赖一样，如果包在安装之前有一个 prepare 脚本，dependencies 和 devDependencies 将被安装。

例子：

npm install gist:101a11beef

• npm install bitbucket:<bitbucketname>/<bitbucketrepo>[#<commit-ish>]：

在 https://bitbucket.org/bitbucketname/bitbucketrepo 安装该包，尝试使用 git 克隆它。

如果 #<commit-ish> 提供，它将用于准确克隆该提交。如果 commit-ish 的格式为 #semver:<semver>,<semver> 可以是任何有效的 semver 范围或确切版本，npm 将在远程存储库中查找与该范围匹配的任何标签或引用，就像它查找注册中心依赖项一样。如果没有指定 #<commit-ish> 或 #semver:<semver>，然后使用 master。

与常规 git 依赖一样，如果包在安装之前有一个 prepare 脚本，dependencies 和 devDependencies 将被安装。

npm install bitbucket:mybitbucketuser/myproject

• npm install gitlab:<gitlabname>/<gitlabrepo>[#<commit-ish>]：

在 https://gitlab.com/gitlabname/gitlabrepo 安装该包，尝试使用 git 克隆它。

如果 #<commit-ish> 提供，它将用于准确克隆该提交。如果 commit-ish 的格式为 #semver:<semver>,<semver> 可以是任何有效的 semver 范围或确切版本，npm 将在远程存储库中查找与该范围匹配的任何标签或引用，就像它查找注册中心依赖项一样。如果没有指定 #<commit-ish> 或 #semver:<semver>，然后使用 master。

例子：

npm install gitlab:mygitlabuser/myproject
npm install gitlab:myusr/myproj#semver:^5.0

您可以组合多个参数，甚至多种类型的参数。例如:

npm install sax@">=0.1.0 <0.2.0" bench supervisor

--tag 参数将应用于所有指定的安装目标。如果存在具有给定名称的标记，则首选标记的版本，而不是较新的版本。

--dry-run 参数将以通常的方式报告安装将执行的操作，而无需实际安装任何东西。

--package-lock-only 参数将只更新 package-lock.json，而不是检查 node_modules 并下载依赖项。

-f 或 --force 参数将强制npm获取远程资源，即使磁盘上存在本地副本。

npm install sax --force

配置

详见 config 帮助文档，许多配置参数对安装有一些影响，因为这是 npm 所做的大部分工作。

这些是与安装相关的一些最常见的选项。

save

• Default: true 除非在使用 npm update 时默认为 false
• Type: Boolean

将已安装的软件包保存为 package.json 文件作为依赖项。

与 npm rm 命令一起使用时，从 package.json 移除依赖关系。

如果设置为 package.json，也将阻止写入 false。

save-exact

• Default: false
• Type: Boolean

保存到 package.json 的依赖项将使用精确的版本进行配置，而不是使用 npm 的默认 semver 范围运算符。

global

• Default: false
• Type: Boolean

以 “global” 模式运行，会将包安装到 prefix 文件夹而不是当前工作目录中。有关行为差异的更多信息，请参阅 folders。

• 软件包被安装到 {prefix}/lib/node_modules 文件夹中，而不是当前工作目录中。
• bin 文件链接到 {prefix}/bin
• 操作说明链接到 {prefix}/share/man

global-style

• Default: false
• Type: Boolean

使 npm 以与全局 node_modules 文件夹相同的布局将包安装到本地 node_modules 文件夹。您的直接依赖项将在 node_modules 中显示，它们所依赖的一切将在其 node_modules 文件夹中扁平化。这显然会消除一些重复数据删除。如果与 legacy-bundling 一起使用，legacy-bundling 优先。

legacy-bundling

• Default: false
• Type: Boolean

使 npm 安装包，以便 1.4 之前的 npm 版本（例如 node 0.8 中包含的版本）可以安装包。这消除了所有自动重复数据删除。如果与 global-style 此选项一起使用 legacy-bundling 将是首选。

omit

• Default: 'dev' | ''
• Type: "dev", "optional", or "peer" (可以设置多次)

要从磁盘上的安装树中省略的依赖类型。

注意

这些依赖项仍然被解析并添加到 package-lock.json 或 npm-shrinkwrap.json 文件中。

如果包类型同时出现在 --include 和 --omit 列表中，那么它将被包括在内。

如果结果省略列表包括 dev，则 NODE_ENV 环境变量将设置 production 为所有生命周期的脚本。

strict-peer-deps

• Default: false
• Type: Boolean

如果设置为 true ，并且没有设置 --legacy-peer-deps，则任何冲突 peerDependencies 都将被视为安装失败，即使 npm 可以根据非对等依赖关系合理地猜测适当的解决方案。

默认情况下，peerDependencies 将使用最近的非对等依赖规范来解决依赖关系图中的冲突，即使这样做会导致某些包收到超出其包 peerDependencies 对象中设置的范围的对等依赖项。

当执行此类和覆盖时，将打印一个警告，解释冲突和涉及的包。如果设置了 --strict-peer-deps，则此警告将被视为失败。

package-lock

• Default: true
• Type: Boolean

如果设置为 false，则在安装时忽略 package-lock.json 文件。如果 save 为 true，将阻止写入 package-lock.json。

此配置不会影响 npm ci。

foreground-scripts

• Default: false
• Type: Boolean

在前台进程中运行已安装包的所有构建脚本(ie, preinstall, install, postinstall) ，将与主 npm 进程共享标准输入、输出和错误。

注意

这通常会使安装运行速度变慢，并且噪音更大，但对调试很有用。

ignore-scripts

• Default: false
• Type: Boolean

如果为 true, npm 不会运行包中指定的 package.json 文件。

注意

如果设置了 ignore-scripts，那些显式地想要运行特定脚本的命令，比如 npm start、npm stop、npm restart、npm test 和 npm run-script 仍然会运行它们想要运行的脚本，但是它们不会运行任何前脚本或后脚本。

audit

• Default: true
• Type: Boolean

当为 "true" 时，将检查报告和当前 npm 命令一起提交到默认注册中心和所有配置了作用域的注册中心。具体提交内容请参见 npm audit 文档。

bin-links

• Default: true
• Type: Boolean

告诉 npm 为包可执行文件创建符号链接（或 Windows 上的 .cmd 连接器命令文件）。

设置为 false 使其不执行此操作。这可以用来解决某些文件系统不支持符号链接的事实，即使在表面上是 Unix 系统上也是如此。

fund

• Default: true
• Type: Boolean

当为 “true” 时，在每个 npm install 的末尾显示一条消息，确认寻求资助的依赖关系的数量。详见 npm fund。

dry-run

• Default: false
• Type: Boolean

表示您不希望 npm 进行任何更改，并且只报告它应该做的事情。这可以传递到任何修改本地安装的命令中，例如：install, update, dedupe, uninstall 以及 pack 和 publish。

注意

其他相关命令不支持此功能，例如 dist-tags, owner 等。

workspace

• Default:
• Type: String (可以设置多次)

启用在当前项目的已配置工作区的上下文中运行命令，同时通过仅运行此配置选项定义的工作区进行过滤。

workspace 配置的有效值如下:

• 工作区名称
• 工作区目录的路径
• 父工作区目录的路径（将导致选择该文件夹中的所有工作区）

为 npm init 命令设置时，可以将其设置为尚不存在的工作空间的文件夹，以创建文件夹并将其设置为项目中的全新工作空间。

此值不会导出到子进程的环境中。

workspaces

• Default: null
• Type: null or Boolean

设置为 true 将在所有配置的工作区中运行该命令。

显式地将此设置为 false 将导致如下命令 install 完全忽略工作空间。当没有显式设置时:

• 在 node_modules 树上操作的命令 (install, update, etc.) 时，将把工作区链接到 node_modules 文件夹中。做其他事情的命令 (test, exec, publish, etc.) 将在根项目上操作，除非在 workspace 配置中指定了一个或多个工作空间。

此值不会导出到子进程的环境中。

include-workspace-root

• Default: false
• Type: Boolean

当为某个命令启用工作区时，请包含工作区根目录。

当为 false 时，通过 workspace 配置指定单个工作空间，或通过 workspaces 标志指定所有工作空间，将导致 npm 仅在指定的工作空间上运行，而不是在根项目上运行。

此值不会导出到子进程的环境中。

install-links

• Default: false
• Type: Boolean

当设置文件: 存在于项目根目录之外的协议依赖项将被打包并安装为常规依赖项，而不是创建符号链接。此选项对工作区没有影响。

算法

给定一个 package{dep} 结构：A{B,C}, B{C}, C{D}，npm install 算法产生：

A
+-- B
+-- C
+-- D

也就是说，B 对 C 的依赖满足于这样一个事实: A 已经导致 C 被安装在更高的级别上。D 仍然安装在顶层，因为没有什么与它冲突。

对于 A{B,C}, B{C,D@1}, C{D@2}，该算法产生：

A
+-- B
+-- C
   `-- D@2
+-- D@1

因为 B 的 D@1 会安装在顶层，所以 C 现在必须为自己私下安装 D@2。该算法是确定性的，但如果请求以不同顺序安装两个依赖项，则可能会生成不同的树。

有关 npm 创建的特定文件夹结构的更详细说明，请参阅 folders。