支持的软件包来源

pnpm 支持从各种来源安装软件包。这些来源分为两类：可信来源 和 外来来源 。

使用外来来源（例如 Git 仓库或直接 tarball URL）时，传递依赖项可能会引入依赖链风险。你可以通过将 blockExoticSubdeps 设置为 true 来阻止传递依赖项使用外来来源。

可信来源#

可信来源对于直接依赖和传递依赖都被认为是安全的。

npm 源#

pnpm add package-name 默认会从 npm 源安装 package-name 的最新版本。

如果在工作空间中执行，该命令将首先去检查这个工作空间中的其他项目是否已经使用了这个指定的包。如果是，已经使用过的版本范围将被安装。

你还可以通过以下方式安装包：

  • 标签：pnpm add express@nightly
  • 版本：pnpm addexpress@1.0.0
  • 版本范围：pnpm add express@2 react@">=0.1.0 <0.2.0"

JSR 源#

添加于：v10.9.0

使用 jsr: 协议前缀从JSR 注册源安装：

pnpm add jsr:@hono/hono
pnpm add jsr:@hono/hono@4
pnpm add jsr:@hono/hono@latest

这和从 npm 安装的方式类似，只是告诉 pnpm 通过 JSR 解析包。

命名注册源#

添加于：v11.1.0

命名注册源 别名会针对特定注册源解析包，而不管默认注册源是什么：

pnpm add work:@corp/lib@^2.0.0
pnpm add gh:@my-org/private-pkg
pnpm add npmjs:left-pad

gh: (GitHub Packages) 以及 npmjs: (公共 npm 注册源) 自 v11.20.0 起无需任何配置即可使用。任何其他别名都必须映射到 pnpm-workspace.yaml 中的 namedRegistries 下，或者自 v11.11.0 起，映射到全局配置文件（config.yaml）中。

工作空间（Workspace）#

When adding dependencies and working within a workspace, packages will be installed from the configured sources, depending on whether or not linkWorkspacePackages is set, and use of the workspace: range protocol.

本地文件系统#

有两种方法可以从本地文件系统安装：

  1. 从 tar 压缩包文件（.tar、.tar.gz 或 .tgz）
  2. 从目录

示例：

pnpm add ./package.tar.gz
pnpm add ./some-directory

当你从目录安装时，会在当前项目的node_modules 目录中生成一个符号链接，因此这和执行 pnpm link 一致。

Since v11.28.0, tarballs compressed with bzip2 can be installed too, both from local files and from remote URLs.

外来来源#

外来来源对开发很有用，但当被传递依赖关系使用时，可能会带来供应链风险。

远程 tarball#

参数必须是一个可访问的 URL，以 "http://" 或 "https://" 开头。

示例：

pnpm add https://github.com/indexzero/forever/tarball/v0.5.6

Git 仓库#

pnpm add <git remote url>

从托管的 Git 提供商安装软件包，并使用 Git 克隆它。

你可以通过以下方式从 Git 安装软件包：

  • 来自默认分支的最新提交：
pnpm add kevva/is-positive
  • Git 提交哈希：
pnpm add kevva/is-positive#97edff6f525f192a3f83cea1944765f769ae2678
  • Git 分支：
pnpm add kevva/is-positive#master
  • 相对于 refs 的 Git 分支：
pnpm add zkochan/is-negative#heads/canary
  • Git 标签：
pnpm add zkochan/is-negative#2.0.1
  • v 前缀的 Git 标签：
pnpm add andreineculau/npm-publish-git#v0.0.7

使用语义版本从 Git 存储库安装#

你可以使用 semver: 参数指定要安装的版本（范围）。例如：

  • 严格的语义版本：
pnpm add zkochan/is-negative#semver:1.0.0
  • v 前缀的严格语义版本：
pnpm add andreineculau/npm-publish-git#semver:v0.0.7
  • 语义版本范围：
pnpm add kevva/is-positive#semver:^2.0.0
  • v 前缀的语义版本范围：
pnpm add andreineculau/npm-publish-git#semver:<=v0.0.7

从 Git 存储库的子目录安装#

你也可以使用 path: 参数从 Git 托管的 monorepo 中仅安装子目录。例如：

pnpm add RexSkz/test-git-subfolder-fetch#path:/packages/simple-react-app

通过完整 URL 从 Git 存储库安装#

如果你想要更明确或使用其他 Git 托管，你可能需要拼出完整的 Git URL：

# git+ssh
pnpm add git+ssh://git@github.com:zkochan/is-negative.git#2.0.1

# https
pnpm add https://github.com/zkochan/is-negative.git#2.0.1

使用托管提供商简写从 Git 存储库安装#

你可以使用协议简写 [provider]: 来表示某些 Git 提供商：

pnpm add github:zkochan/is-negative
pnpm add bitbucket:pnpmjs/git-resolver
pnpm add gitlab:pnpm/git-resolver

如果省略 [provider]:，则默认为 github:。

结合不同参数从 Git 存储库安装#

可以通过用 & 分隔来组合多个参数。这对于 monorepo 的分叉是有用的：

pnpm add RexSkz/test-git-subdir-fetch.git#beta\&path:/packages/simple-react-app

从beta 分支安装，并仅安装 /packages/simple-react-app 子目录。

Git 依赖如何解析#

pnpm 11 keeps the specifier's transport as part of the recorded URL. Since v11.21.0 it records an SSH URL only when the specifier itself asks for one (git+ssh:// or git@host:...): a shorthand like owner/repo resolves and records over HTTPS, so a lockfile written on a machine with SSH keys still installs on a CI runner without them. 由旧版 pnpm 记录的 SSH URL 可通过 pnpm update <package> 重新以 HTTPS 记录。

Since v11.28.0, pnpm also fetches the committed submodules of a Git dependency.

Since v11.28.0, pnpm runs ssh in batch mode when it fetches a Git dependency over SSH, so ssh cannot stop to ask for a key passphrase or a host key confirmation; the install fails with the ssh error instead. Load a key that needs a passphrase into an SSH agent before installing, and add the host to known_hosts first. An ssh command set through GIT_SSH_COMMAND, GIT_SSH, or the core.sshCommand Git setting is used as is.