包管理

vp 会检测并运行当前工作区的包管理器。这些命令可通过全局 CLI和项目本地 CLI使用。

概述

使用 Vite+ 来管理 pnpm、npm、Yarn 和 Bun 之间的依赖关系。无需在 pnpm install、npm install、yarn install 和 bun install 之间切换，你可以继续使用 vp install、vp add、vp remove 以及其余的 Vite+ 包管理命令。

Vite+ 按照以下顺序检测包管理器：

1. packageManager 位于 package.json 中
2. devEngines.packageManager 位于 package.json 中
3. pnpm-workspace.yaml
4. pnpm-lock.yaml
5. yarn.lock 或 .yarnrc.yml
6. package-lock.json
7. bun.lock 或 bun.lockb
8. .pnpmfile.cjs 或 pnpmfile.cjs
9. bunfig.toml
10. yarn.config.cjs

如果上述文件均不存在，vp 默认回退到 pnpm。Vite+ 会自动下载匹配的包管理器并使用它来运行你执行的命令，但包管理器检测过程绝不会重写 package.json。当项目需要显式声明确切版本时，请使用 vp env pin <package-manager>@<version>。

devEngines.packageManager 字段接受单个对象或对象数组，其 version 可以是 semver 范围：

{
  "devEngines": {
    "packageManager": {
      "name": "pnpm",
      "version": "^11.0.0",
      "onFail": "download"
    }
  }
}

当可能时，范围会解析为已下载且满足条件的版本，否则会解析为 npm 注册表中最新的满足条件版本。该范围本身仍是唯一事实来源；Vite+ 绝不会将其冻结为精确的 packageManager 固定版本。当同时声明了 packageManager 和 devEngines.packageManager 时，packageManager 字段决定选择结果，而当它不满足 devEngines 约束时，Vite+ 会发出警告（vp env doctor 会显示详细信息）。

Vite+ 当前会下载所声明的包管理器（即 onFail: "download" 的行为）；其他 onFail 值虽被接受，但尚未做区分处理。

显式的 packageManager 字段（或 devEngines.packageManager 声明）也会影响匹配的包管理器 shim。如果项目包含 packageManager: "[email protected]"，npm 和 npx 会使用 npm 10.9.4。其他生成的别名对也遵循相同方式：pnpm/pnpx、yarn/yarnpkg 以及 bun/bunx。不匹配的工具不会被转换；在 pnpm 项目中使用 npm 仍然会解析为 npm。

用法

vp install

常见安装流程：

vp install
vp install --frozen-lockfile
vp install --lockfile-only
vp install --filter web
vp install -w

vp install 会映射到检测到的包管理器的正确底层安装行为，包括适用于 pnpm、npm、Yarn 和 Bun 的正确锁文件标志。

全局包

使用 -g 标志来安装、更新或移除全局安装的包：

• vp install -g <pkg> 全局安装一个包
• vp uninstall -g <pkg> 移除一个全局包
• vp update -g [pkg] 更新一个全局包或全部全局包
• vp list -g [pkg] 列出全局包
• vp outdated -g [pkg] 打印过期的包

更新会保留安装包时使用的版本规范：从 dist-tag（例如 vp install -g some-pkg@nightly）安装的包会更新到该标签的最新版本，而版本范围则会保持在该范围内。使用不同的规范重新安装（例如 vp update -g some-pkg@latest）即可切换，或者向 vp update -g 传入 --latest，将包切换到 latest 标签并清除其记录的规范。vp outdated -g 会同时报告与记录的规范匹配的最新版本（Wanted），以及 latest 标签上的最新版本。

WARNING

这些命令不会与底层包管理器的全局安装目录交互。

相反，Vite+ 会将其全局包存储在已解析数据目录下的 packages/ 中。这些包在不同的 Node.js 版本之间仍然可用。

因此，诸如 vp link 之类的命令不会影响 Vite+ 的全局包，并且不会出现在 vp list -g 中。

管理依赖

Vite+ 提供了所有熟悉的包管理命令：

• vp install 会为项目安装当前的依赖图
• vp add <pkg> 将包添加到 dependencies，使用 -D 添加到 devDependencies
• vp remove <pkg> 移除包
• vp update 更新依赖
• vp dedupe 在包管理器支持的情况下减少重复依赖条目
• vp outdated 显示可用更新
• vp list 显示已安装的包
• vp why <pkg> 解释为什么会安装该包
• vp info <pkg> 显示包的注册表元数据
• vp rebuild 重新构建原生模块（例如切换 Node.js 版本后）
• vp link 和 vp unlink 管理本地包链接
• vp dlx <pkg> 运行包的二进制文件而不将其添加到项目中
• vp pm <command> 转发原始的、与包管理器相关的命令；当你需要超出已标准化的 vp 命令集的行为时使用

命令指南

安装

当你想安装与当前 package.json 和锁文件完全一致的内容时，使用 vp install。

• vp install 是标准安装命令
• vp install --frozen-lockfile 如果锁文件需要更改则失败
• vp install --no-frozen-lockfile 允许显式更新锁文件
• vp install --lockfile-only 不执行完整安装，仅更新锁文件
• vp install --prefer-offline 和 vp install --offline 优先或强制使用缓存包
• vp install --ignore-scripts 跳过生命周期脚本
• vp install --filter <pattern> 在 monorepo 中限制安装范围
• vp install -w 在工作区根目录安装

Git 和远程 tarball 依赖（npm v12+）

npm v12 默认不再解析 Git 依赖（github:、git+https:）和远程 tarball URL；此类安装会失败并显示 EALLOWGIT / EALLOWREMOTE。使用 npm 的 allow-git / allow-remote 配置，即可按项目选择重新启用。

全局安装

当你想让包管理器管理的工具在单个项目之外可用时，使用这些命令：

• vp install -g typescript
• vp uninstall -g typescript
• vp update -g
• vp list -g
• vp outdated -g

添加和移除

使用 vp add 和 vp remove 进行日常的依赖编辑，而不是手动编辑 package.json。

• vp add react
• vp add -D typescript vitest
• vp add -O fsevents
• vp add --save-peer react
• vp add react --ignore-scripts
• vp remove react
• vp remove --filter web react

更新、压缩和查看过期

使用这些命令来维护依赖图：

• vp update 刷新包到更新版本
• vp outdated 显示哪些包有可用的新版本
• vp dedupe 请求包管理器在可能的情况下折叠重复项

检查

当你需要了解依赖的当前状态时，使用这些命令：

• vp list 显示已安装的包
• vp why react 解释为什么安装了 react
• vp info react 显示注册表元数据，如版本和 dist-tags

这些命令会显示包管理器安装的包。它们不会显示 Vite+ 捆绑或编译的工具。运行 vp toolchain [tool] 可显示这些工具，包括 Vite、Rolldown 和 Oxc。为了输出易于阅读，vp why 会在 Vite+ 同时提供该包时显示提示。

重建

当需要重新编译原生模块时，使用 vp rebuild；例如在切换 Node.js 版本后，或当 C/C++ 加载失败的扩展无法加载时。

• vp rebuild 重新构建所有原生模块
• vp rebuild <package...> 仅重新构建列出的包
• vp rebuild -- <args> 将额外参数传递给底层包管理器

vp rebuild
vp rebuild better-sqlite3 sharp
vp rebuild -- --update-binary

vp rebuild 是 vp pm rebuild 的简写。

对于 pnpm v10+，裸用 vp rebuild 只会重新构建其构建脚本列在 onlyBuiltDependencies 中（或通过 pnpm approve-builds 批准）的包；如果要强制重新构建并绕过批准门槛，请显式指定包名。

依赖构建脚本（npm v12+）

npm v12 会跳过依赖安装脚本（preinstall / install / postinstall，包括隐式的 node-gyp 构建），除非 package.json 中的 allowScripts 字段涵盖这些脚本；安装会成功，但 npm 会警告被跳过的内容。vp pm approve-builds 用于管理该允许列表：

• vp pm approve-builds <pkg...> 批准指定的包（npm approve-scripts）
• vp pm approve-builds !<pkg...> 拒绝这些包（npm deny-scripts）
• vp pm approve-builds --all 批准当前所有待处理的包
• vp pm approve-builds 列出其脚本尚未被涵盖的包

批准操作只会记录允许列表：较早安装过程中被跳过的脚本不会运行，直到你执行 vp rebuild <pkg>。在 npm 11.16 - 11.x 中，相同的命令也能正常工作，但 npm 会将允许列表视为建议，仍然会运行脚本。

高级

当你需要更低级别的包管理器行为时，使用这些命令：

• vp link 和 vp unlink 管理本地开发链接
• vp dlx create-vite 运行包二进制文件而不将其保存为依赖
• vp pm <command> 直接转发到解析的包管理器

示例：

vp pm config get registry
vp pm cache clean -- --force
vp pm audit --json

分阶段发布

vp pm stage 提供了 npm 的分阶段发布 工作流：构建产物会被上传到暂存区（不需要 2FA，适合 CI），然后维护者可以从受信任的设备上批准或拒绝它（2FA）。它会适配检测到的包管理器。

vp pm stage publish              # 将包上传到暂存区（不需要 2FA）
vp pm stage list                 # 列出暂存的版本
vp pm stage view <stage-id>      # 查看暂存版本
vp pm stage download <stage-id>  # 下载暂存的 tarball
vp pm stage approve <stage-id>   # 推送到正式注册表（2FA）
vp pm stage reject <stage-id>    # 丢弃暂存版本（2FA）

• pnpm（pnpm stage，需要 pnpm ≥ 11.3）和 npm（npm stage，需要 npm ≥ 11.15 且 Node ≥ 22.14）会直接透传。
• yarn（Berry）使用其 npm 插件（yarn npm publish --staged、yarn npm stage …）；view/download 会回退到 npm。
• yarn Classic 和 bun 不支持分阶段发布，会回退到 npm stage。

包管理器完整性验证

packageManager 固定版本可以携带完整性哈希（[email protected]+sha512.…）。corepack use 会写入该哈希。Vite+ 会对与 Corepack 相同的构件进行哈希处理：

• Yarn 2 及更高版本提取出的 CLI 二进制文件（bin/yarn.js）
• npm、pnpm 和 Yarn Classic 的 npm 包 tarball

Vite+ 会在安装 Yarn 时对 CLI 进行一次哈希处理，并记录它验证过的固定版本。后续命令会将自身的固定版本与该记录进行比较。不匹配记录的固定版本会导致检查失败，并停止命令。Corepack 也会为自己的缓存保留同类记录。