Node.js v20.11.1 文档


Corepack#

稳定性: 1 - 实验性的

Stability: 1 - Experimental

Corepack 是一个实验性工具,可帮助管理包管理器的版本。它为每个 支持的包管理器 公开二进制代理,当被调用时,它将识别为当前项目配置的任何包管理器,如果需要透明地安装它,最后运行它而不需要明确的用户交互。

Corepack is an experimental tool to help with managing versions of your package managers. It exposes binary proxies for each supported package manager that, when called, will identify whatever package manager is configured for the current project, transparently install it if needed, and finally run it without requiring explicit user interactions.

此特性简化了两个核心工作流程:

This feature simplifies two core workflows:

  • 它简化了新贡献者的加入,因为他们不必再遵循特定于系统的安装过程,只需拥有你想要的包管理器。

    It eases new contributor onboarding, since they won't have to follow system-specific installation processes anymore just to have the package manager you want them to.

  • 它允许你确保团队中的每个人都将使用你想要的包管理器版本,而无需他们在每次需要进行更新时手动同步它。

    It allows you to ensure that everyone in your team will use exactly the package manager version you intend them to, without them having to manually synchronize it each time you need to make an update.

工作流程#

Workflows

启用该功能#

Enabling the feature

由于处于实验状态,目前需要显式地启用 Corepack 才能生效。为此,则运行 corepack enable,其将在你的环境中设置 node 二进制文件旁边的符号链接(并在必要时覆盖现有的符号链接)。

Due to its experimental status, Corepack currently needs to be explicitly enabled to have any effect. To do that, run corepack enable, which will set up the symlinks in your environment next to the node binary (and overwrite the existing symlinks if necessary).

从现在开始,对 支持的二进制文件 的任何调用都将无需进一步设置即可工作。如果你遇到问题,请运行 corepack disable 从你的系统中删除代理(并考虑在 Corepack 仓库 上打开一个问题让我们知道)。

From this point forward, any call to the supported binaries will work without further setup. Should you experience a problem, run corepack disable to remove the proxies from your system (and consider opening an issue on the Corepack repository to let us know).

配置包#

Configuring a package

Corepack 代理将在当前目录层次结构中找到最近的 package.json 文件以提取其 "packageManager" 属性。

The Corepack proxies will find the closest package.json file in your current directory hierarchy to extract its "packageManager" property.

如果该值对应于 支持的包管理器,Corepack 将确保对相关二进制文件的所有调用都针对请求的版本运行,如果需要则按需下载,如果无法成功检索则中止。

If the value corresponds to a supported package manager, Corepack will make sure that all calls to the relevant binaries are run against the requested version, downloading it on demand if needed, and aborting if it cannot be successfully retrieved.

你可以使用 corepack use 要求 Corepack 更新你的本地 package.json 以使用你选择的包管理器:

You can use corepack use to ask Corepack to update your local package.json to use the package manager of your choice:

corepack use pnpm@7.x # sets the latest 7.x version in the package.json
corepack use yarn@* # sets the latest version in the package.json 

升级全局版本#

Upgrading the global versions

当在现有项目之外运行时(例如运行 yarn init 时),Corepack 将默认使用与每个工具的最新稳定版本大致对应的预定义版本。可以通过运行 corepack install 命令以及你希望设置的包管理器版本来覆盖这些版本:

When running outside of an existing project (for example when running yarn init), Corepack will by default use predefined versions roughly corresponding to the latest stable releases from each tool. Those versions can be overridden by running the corepack install command along with the package manager version you wish to set:

corepack install --global yarn@x.y.z 

或者,可以使用标签或范围:

Alternately, a tag or range may be used:

corepack install --global pnpm@*
corepack install --global yarn@stable 

离线工作流程#

Offline workflow

很多生产环境没有网络访问权限。由于 Corepack 通常直接从其仓库下载包管理器版本,它可能与此类环境发生冲突。为避免这种情况发生,请在你仍有网络访问权限时调用 corepack pack 命令(通常在你准备部署映像的同时)。这将确保即使没有网络访问,所需的包管理器也可用。

Many production environments don't have network access. Since Corepack usually downloads the package manager releases straight from their registries, it can conflict with such environments. To avoid that happening, call the corepack pack command while you still have network access (typically at the same time you're preparing your deploy image). This will ensure that the required package managers are available even without network access.

pack 命令有 各种标志。有关详细信息,请参阅详细的 Corepack 文档

The pack command has various flags. Consult the detailed Corepack documentation for more information.

支持的包管理器#

Supported package managers

以下二进制文件通过 Corepack 提供:

The following binaries are provided through Corepack:

包管理器二进制名称
Yarnyarn, yarnpkg
pnpmpnpm, pnpx

常见问题#

Common questions

Corepack 如何与 npm 交互?#

How does Corepack interact with npm?

虽然 Corepack 可以像任何其他包管理器一样支持 npm,但默认情况下不启用它的 shim。这有几个后果:

While Corepack could support npm like any other package manager, its shims aren't enabled by default. This has a few consequences:

  • 总是可以在配置为与另一个包管理器一起使用的项目中运行 npm 命令,因为 Corepack 无法拦截它。

    It's always possible to run a npm command within a project configured to be used with another package manager, since Corepack cannot intercept it.

  • 虽然 npm"packageManager" 属性中的有效选项,但缺少 shim 将导致使用全局 npm。

    While npm is a valid option in the "packageManager" property, the lack of shim will cause the global npm to be used.

运行 npm install -g yarn 不起作用#

Running npm install -g yarn doesn't work

npm 防止在进行全局安装时意外覆盖 Corepack 二进制文件。为避免此问题,请考虑以下选项之一:

npm prevents accidentally overriding the Corepack binaries when doing a global install. To avoid this problem, consider one of the following options:

  • 不要运行这个命令;Corepack 无论如何都会提供包管理器二进制文件,并确保请求的版本始终可用,因此不需要显式安装包管理器。

    Don't run this command; Corepack will provide the package manager binaries anyway and will ensure that the requested versions are always available, so installing the package managers explicitly isn't needed.

  • npm install 加上 --force 标志;这将告诉 npm 可以覆盖二进制文件,但你将在此过程中删除 Corepack 文件。(运行 corepack enable 将它们添加回来。)

    Add the --force flag to npm install; this will tell npm that it's fine to override binaries, but you'll erase the Corepack ones in the process. (Run corepack enable to add them back.)