Vite+

包管理 ​

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 范围：

json
{
  "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/pn/pnx、yarn/yarnpkg 以及 bun/bunx。不匹配的工具不会被改写；在 pnpm 项目中调用 npm 仍会解析为 npm。

用法 ​

bash
vp install

常见安装流程：

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

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

全局包 ​

INFO

使用 -g 执行全局软件包操作需要全局 CLI。

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

  • vp install -g <pkg> 全局安装一个软件包
  • vp install -g --node <version> <pkg> 使用指定的 Node.js 版本全局安装一个软件包
  • vp uninstall -g <pkg> 移除一个全局软件包
  • vp update -g [pkg] 更新一个全局软件包或全部软件包
  • vp list -g [pkg] 列出全局软件包
  • vp outdated -g [pkg] 打印过期的软件包

不使用 --node 时，vp install -g 使用当前目录解析出的 Node.js 版本，因此项目固定版本的优先级高于 vp env default。请参阅 Node.js 选择。

更新会保留安装软件包时使用的版本规范：从 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> 提供根据检测到的包管理器调整的其他包管理命令

INFO

vp list 和 vp rebuild 快捷命令仅在全局 CLI 中可用。使用项目本地 CLI 时，请使用 vp pm list 和 vp pm rebuild。

命令指南 ​

安装 ​

当你想安装与当前 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 在工作区根目录安装

INFO

选项支持取决于检测到的包管理器及其版本。不受支持的选项会使 vp 在运行包管理器命令前退出并显示错误。

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> 将额外参数传递给底层包管理器
bash
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> 提供根据检测到的包管理器调整的其他包管理命令。

    • 依赖： ci、prune、list、rebuild、approve-builds
    • 补丁： patch、patch-commit
    • 打包和发布： pack、version、publish、stage、dist-tag、deprecate
    • 检查： view、search、licenses、audit、fund、ping
    • 身份验证和访问： login、logout、whoami、token、owner、team
    • 配置： config、cache
    • 软件包清单： pkg get、pkg set、pkg delete、pkg fix

    命令支持取决于包管理器及其版本。运行 vp pm --help 列出命令，或运行 vp pm <command> --help 查看可用选项。

示例：

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

软件包清单 ​

vp pm pkg 使用检测到的包管理器读取和更新 package.json 中的字段。

bash
vp pm pkg get name
vp pm pkg set scripts.build="vite build"
vp pm pkg set private=true --json
vp pm pkg delete scripts.build
vp pm pkg fix

npm 从 7.20.0 起支持 get、set 和 delete，从 9.8.0 起支持 fix。pnpm 从 11.3.0 起支持全部四个命令；Bun 从 1.2.19 起通过 bun pm pkg 支持这些命令。Yarn 和不受支持的版本会显示警告并成功退出，不会更改清单；这与 vp pm patch 的行为一致。

原生行为会得到保留。例如，npm 的 get 会返回 JSON，而 pnpm 默认会输出不带引号的单个字符串值。使用 --json 可请求 JSON 输出，或将传给 set 的值解析为 JSON。其他原生命令选项可放在 -- 之后传入。fix 执行的修正取决于包管理器。

分阶段发布 ​

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

bash
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 4.16.0 及更高版本使用其 npm 插件（yarn npm publish --staged、yarn npm stage …）。view 和 download 子命令，以及指定 tarball 或目录目标的 publish，会回退到 npm stage。
  • 低于 4.16.0 的 Yarn 版本和 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 也会为自己的缓存保留同类记录。

© 2026 VoidZero Inc. and Vite+ contributors.