pnpm 12 有什么不同

pnpm 12 是 Rust 中 pnpm 的重写版本,并且是稳定版。升级不应该感觉像是一次迁移。除了下面的差异之外,它保留了 pnpm 11 的命令、标志、设置和锁文件格式,并且文档对两个版本都适用。

有八处不同。其中六处会改变结果,另外两处会拒绝 pnpm 11 接受的命令行语法。这篇文章将它们汇总在了一起。

项目感知的全局二进制#

A globally installed node, deno, or bun now runs the version the current project pins.

A project pins a runtime through devEngines.runtime or by installing the runtime as a dependency. Run node inside that project and you get the pinned version. Run it outside any project and you get the global one. You no longer need a separate version manager for this.

控制此行为的设置是 globalShims,详细说明请参阅 项目感知型全局二进制文件。

Git 依赖解析#

For repositories on GitHub, GitLab, and Bitbucket, a specifier now only says which repository you want, not how to reach it. All of these name the same dependency and resolve the same way:

kevva/is-positive
github:kevva/is-positive
git+https://github.com/kevva/is-positive.git
git+ssh://git@github.com/kevva/is-positive.git

Each resolves through the host's HTTPS URL, and pnpm never records an SSH URL for those hosts. How a machine reaches the host is that machine's Git configuration, not something the project decides. A lockfile written on a laptop with SSH keys installs on a CI runner without them.

pnpm 11 tried transports in turn and could record git@github.com:owner/repo.git, which then failed for everyone without a key for that host. If an older lockfile has such an entry, run pnpm update <package> once to re-resolve it. pnpm does not rewrite the entry on its own. The lockfile is the record of what to install, and pnpm leaves it alone until you ask.

To reach private repositories over SSH, tell Git to rewrite the URL:

git config --global url."git@github.com:".insteadOf https://github.com/

pnpm shells out to git, so the rewrite applies to every Git operation pnpm runs. Unknown hosts and URLs with embedded credentials are covered in How Git dependencies are resolved.

命名软件包管理器#

pnpm 12 can install the other package managers: npm, Yarn Classic, Yarn Berry, Yarn 6 (yarnpkg/zpm), and Bun. As a result, naming one of them means the tool, not the npm package that shares its name.

Those npm packages are not the tool. yarn on npm stops at Classic. Yarn 4 is published as @yarnpkg/cli-dist. Yarn 6 is not on npm at all. node and deno on npm are wrappers that download a build. 以前,pnx yarn@4 install 会因版本缺失而失败,而 pnpm add -g yarn 安装的则是 Yarn 1。

pnpm 11 pnpm 12
pnpm add yarn 安装 npm 包 yarn 在 packageManager / devEngines.packageManager 中记录项目的包管理器
pnpm add -g yarn 安装 Yarn Classic 安装当前的 Yarn 主线
pnpm add -g node / pnpm add -g deno 安装一个包装器包 安装该 Node.js 或 Deno 版本
pnx node@22 / pnx deno 安装一个包装器包 运行该版本
全局安装的软件包管理器 总是全局副本 遵循项目的引脚定义(如果存在的话)。

A specifier that points at a specific package still installs that package. pnpm add yarn@npm:yarn@1.22.22 gives you the npm package, and pnx yarn@yarnpkg/berry runs Yarn from its repository.

Two more things follow. A git-hosted dependency is built with the package manager its own repository asks for, so a repository that uses Yarn installs on a machine that has only pnpm. And pnpm shim add yarn links a yarn command that runs whatever version the current project pins. pnpm never creates such a shim as a side effect of pnpm setup or an install, because the shim shadows the rest of your PATH.

完整描述请见 其他包管理器。

循环依赖图的锁文件#

pnpm 12 breaks dependency cycles at a fixed place. It orders the packages in a cycle by package ID and always cuts the same edge, no matter where the install entered the cycle. pnpm 11 cut wherever it happened to walk in.

The lockfile now depends only on the dependency graph. Reorder the packages globs in pnpm-workspace.yaml, reorder entries in package.json, or install twice, and you get the same bytes. In pnpm 11 a project with cycles could get a different lockfile each time. Workspaces with many cycles also resolve peers 2–3× faster and use about 25% less memory. Their lockfiles shrink too, because a package inside a cycle no longer gets a separate peer variant for every path that reaches it.

Existing lockfiles keep working. --frozen-lockfile installs them as they are, and an install that doesn't re-resolve leaves them untouched. The first install that does re-resolve rewrites the peer variants of cyclic packages, so expect a one-time lockfile diff. Details in How peers are resolved.

On Linux, the default packageImportMethod: auto now tries a hardlink before a reflink. Hardlinks are cheaper to create, and on btrfs this roughly halves the time an install spends materializing node_modules from a warm store.

Cloning is still the second choice. A store that refuses a hardlink gets a clone, and a store that refuses that too gets a copy. packageImportMethod: clone still asks for a clone outright. Pick that if you edit files inside node_modules, because a hardlinked file is the store's file. Nothing changes on ext4, which never supported cloning, so auto already hardlinked there. macOS keeps clone-first because APFS clonefile is fast.

pnpm 11 keeps clone-first on Linux. Changing what the default writes to disk is not something for a point release.

engineStrict and optional subtrees#

With engineStrict on, pnpm 12 fails the install when a package that is being installed depends, through regular dependencies, on a package with an incompatible engine. It no longer matters that the whole subtree sits under an optionalDependencies entry. pnpm 11 installs the package and prints an install-check warning.

What gets skipped has not changed. A package reachable only through optional edges, or through a package that was itself skipped, is still skipped in both versions (#13286).

pnpm install --resolution-only 已经消失#

pnpm 12 未实现该标志并拒绝它:

error: unexpected argument '--resolution-only' found

The flag existed to print peer dependency issues. pnpm peers check does that instead. It reads the issues from the lockfile, so it needs neither a re-resolution nor an install:

pnpm peers check

If a CI script calls --resolution-only, replace it before switching to pnpm 12.

Explicit frozen-lockfile values#

pnpm install --frozen-lockfile false is no longer supported. Use pnpm install --no-frozen-lockfile to disable frozen-lockfile mode. To enable it, use pnpm install --frozen-lockfile without a separate true argument (pnpm/pnpm#14741).

试试看#

latest on npm still points at the pnpm 11 line, so install pnpm 12 from the latest-12 tag. Homebrew、winget、Scoop 和 Chocolatey 尚未提供它。 Installing pnpm 12 lists the ways to install it.

如果你遇到任何问题,请提交报告。