企业官网建设流程全解析

• AI 技能
• 人工智能

本指南以 pnpm v11/v12 的完整 CLI 命令体系为主线，覆盖依赖安装、脚本运行、workspace 过滤、补丁、全局包、运行时管理、发布与原生版本管理、任务编排等全部命令，并结合仓库内 core-cli.md 与 core-config.md、best-practices-migration.md 等关联文档，说明每条命令的使用场景与 v12 行为差异。读完本文，你将能够熟练使用 pnpm 完成从日常依赖管理到 monorepo 发布的全流程操作，并在迁移或升级时避开 v11 → v12 的坑。

版本前提：本指南基于 pnpm 12.x（2026-09-25 生成）。pnpm v12 是 v11 的 Rust 重写，稳定可用，且保留了 v11 的全部命令、flags、settings 与 lockfile 格式，因此本文绝大部分内容同时适用于 v11 与 v12。少数行为差异与一个被移除的 flag 会在对应小节标注（详见 best-practices-migration.md）。

一、安装类命令：日常依赖增删改查

pnpm 的安装命令与 npm/yarn 形态相似，但带有独特的语义与别名：

pnpm install # 安装所有依赖（别名：pnpm i） pnpm add <pkg> # 作为生产依赖安装 pnpm add -D <pkg> # 作为 devDependency 安装（也可用 -d） pnpm add -O <pkg> # 作为 optionalDependency 安装（也可用 -o） pnpm add -E <pkg> # 以精确版本写入（也可用 -e） pnpm add <pkg>@<version> # 安装指定版本，例如 pnpm add lodash@4.17.21 pnpm remove <pkg> # 移除依赖（别名：rm、uninstall、un） pnpm update # 按 semver 范围更新（别名：up） pnpm update --latest # 忽略 semver 范围直接升到最新（-L） pnpm update -i # 交互式更新

干净 / 可复现安装

对于 CI 与团队协作场景，可复现性至关重要：

pnpm install --frozen-lockfile # 若 lockfile 需要变化则直接失败（CI 中自动启用） pnpm ci # 干净安装 = pnpm clean + install --frozen-lockfile pnpm clean # 删除所有 workspace 项目的 node_modules（别名：purge） pnpm clean --lockfile # 连同 pnpm-lock.yaml 一起删除

关于完整性校验有两个重要事实：自 v11 起，若 tarball 与 lockfile 中的完整性记录不匹配，会直接抛出硬错误ERR_PNPM_TARBALL_INTEGRITY；如需更新校验和，只有在你已亲自核实新字节可信时才应使用pnpm install --update-checksums。此外，CI 中 pnpm 也会对由更新版本 pnpm 生成的 lockfile 直接失败，因此务必保证 CI 与本地使用同一 pnpm 版本。

v12 破坏性变更：pnpm install --resolution-only已被移除并直接报错，官方替代方案是pnpm peers check（从 lockfile 读取 peer 依赖问题）。升级前请在 CI 脚本中 grep 该 flag。

二、脚本命令：运行、写入与隔离执行

pnpm run <script> # 运行脚本（也可直接写 pnpm <script>） pnpm run build -- --watch # 向脚本透传额外参数 pnpm run --if-present build # 脚本不存在时静默跳过 pnpm set-script test "vitest run" # 新增/更新 package.json scripts 条目（别名：ss） pnpm exec <cmd> # 运行本地二进制，如 pnpm exec eslint .

两个值得注意的规则：

• 隐藏脚本：以.开头的脚本名（如.helper）不能被直接调用，只能被其他脚本内部引用，用于组织内部步骤。
• 内置命令与脚本同名冲突：名为clean、setup、deploy、rebuild的 package.json 脚本会优先于同名内置命令执行。若确实要调用内置命令，用pnpm pm <name>强制（例如pnpm pm clean）。该冲突处理是 v11 起的行为，迁移细节见 best-practices-migration.md。

dlx / pnx：不安装即可执行

pnx create-vite my-app # pnx == pnpm dlx == pnpx pnpm dlx degit user/repo dest pnx shx@catalog: # 支持 catalog: 协议 pnx --package=@scope/tool tool --help # 显式指定来自哪个包

dlx/pnx会遵循供应链安全相关设置（minimumReleaseAge、trustPolicy），并默认使用全局虚拟存储。在交互式终端中，若某个依赖的构建脚本被跳过，会提示你确认（或使用--allow-build预先批准），相关安全模型见 features-supply-chain-security.md。

pnx 运行其他包管理器 / 运行时（v12）

v12 中，直接以包管理器或运行时命名（npm、yarn、bun、node、deno）会真实供应对应工具，而不是安装同名 npm 包：

pnx yarn@4 install pnx npm@11 ci pnx node@22 --version pnx yarn@npm:yarn@1.22.22 # 能定位到 npm 包的 specifier，则按原样安装该包

注意最后一条：yarn@npm:yarn@1.22.22这种显式指向 npm 包的写法仍会安装 Classic Yarn 包；而裸写yarn@4安装的是 Yarn 工具本身（详见 features-global-virtual-store.md）。

三、Workspace 命令：递归执行与过滤

pnpm -r run <script> # 在所有 packages 中运行（别名：--recursive） pnpm --filter <pattern> run <script> pnpm --filter "./packages/**" run build pnpm --filter "@myorg/*" run lint pnpm -r --parallel run dev

Filter 模式

pnpm --filter <pkg-name> <cmd> # 按包名过滤（简写 -F） pnpm --filter "./packages/core" test pnpm --filter "...@scope/app" build # 该包 + 它的全部依赖 pnpm --filter "@scope/core..." test # 该包 + 它的全部依赖者 pnpm --filter "...[origin/main]" build # 自某 git ref 以来发生变更的包

过滤与递归是 monorepo 的核心操作手段，更多 workspace 协议与共享 lockfile 的内容见 core-workspaces.md。

四、补丁命令：修改第三方包

pnpm patch <pkg>@<version> # 打开可编辑副本，并打印路径 pnpm patch-commit <path> # 将修改写入 patches/*.patch 并记录 pnpm patch-remove <pkg>@<version>

补丁流程为：pnpm patch解包出一份可编辑副本 → 修改代码 →pnpm patch-commit落盘为 patch 文件并登记到patchedDependencies（配置在pnpm-workspace.yaml）。注意 v11 起allowNonAppliedPatches更名为allowUnusedPatches，且ignorePatchFailures已被移除——补丁失败现在总是抛错（见 features-patches.md 与 best-practices-migration.md）。

五、本地包链接

pnpm link <dir> # 将某个路径链接进当前项目的 node_modules（仅接受路径！） pnpm add -g . # 将当前包的 bin 注册到全局

v11 破坏性变更：pnpm link只接受相对/绝对路径，不再支持全局存储解析、不再支持--global、也不支持无参的裸pnpm link。要把 bin 暴露到系统全局，请使用pnpm add -g .。

六、全局包（v11 起隔离安装）

v11 重新设计了pnpm add -g：每个全局包（或每个分组）拥有独立的安装目录（含自己的package.json、node_modules/与 lockfile），避免全局工具之间因 peer/hoisting 冲突互相破坏。安装位置为{pnpmHomeDir}/global/v11/{hash}/，并共享全局虚拟存储。

pnpm add -g typescript prettier # 空格分隔 = 各自独立的隔离安装 pnpm add -g eslint,prettier # 逗号分隔 = 共享同一个安装组 pnpm add -g --allow-build=esbuild esbuild # 预先批准构建脚本 pnpm remove -g <pkg> pnpm list -g # 深度 0 下始终可用 pnpm bin -g # 显示全局 bin 目录（$PNPM_HOME/bin）

关键约束：pnpm install -g（无参数）不受支持，请改用pnpm add -g <pkg>；升级后记得运行pnpm setup，使$PNPM_HOME/bin进入 PATH。pnpm list -g --depth=<n>（n>0）仅对单个安装组有效（详见 features-global-virtual-store.md）。

七、项目感知的命令 shims（v12）

全局安装的node/deno/bun（以及被 shim 的工具）会运行当前项目所固定的版本——无需版本管理器，无需 shell 钩子。pnpm 会向上查找提供该命令的最近项目。

pnpm shim add yarn # 生成一个 yarn，运行当前项目固定的版本 pnpm shim ls pnpm shim rm yarn

要点：shims 绝不会作为pnpm setup/install 的副作用被写入（因为它会遮蔽 PATH），该行为受globalShims设置管控。自 v12.3.0 起，pnpm 写入的每个项目感知全局命令在各平台都是原生可执行文件（Windows 上是.exe，而非.cmd/.ps1）。全局包、shims 与多包管理器的完整说明见 features-global-virtual-store.md。

八、运行时管理（Node / Deno / Bun）

pnpm runtime set node 22 -g # 安装并暴露 node（别名：rt） pnpm runtime set node lts -g pnpm runtime set deno 2 -g pnpm install --no-runtime # 跳过安装 devEngines.runtime 中的运行时条目

运行时固定信息记录在package.json的devEngines.runtime中；runtime命令负责按需安装对应版本。运行时与包管理器固定的完整配置（devEngines.packageManager、pmOnFail等）见 core-config.md。

九、Store 管理

pnpm store path # 打印 store 位置（prune 后还会打印释放的空间大小） pnpm store prune # GC 未被引用的包（含全局虚拟存储链接） pnpm store status

pnpm 使用内容寻址 store：所有包只全局存储一份，再通过硬链接进入各项目node_modules，以此去重磁盘占用并加速安装（架构细节见 core-store.md）。注意pnpm store path的行为在 v11/v12 中会附带打印 prune 释放的体积。

十、检查与 Registry 命令

pnpm list # 列出依赖树（别名：ls） pnpm why <pkg> # 反向依赖树（谁依赖了它，子树去重） pnpm why --find-by=<finder> # 使用 .pnpmfile.mjs 中的自定义 finder pnpm outdated # 检查过期依赖 pnpm audit # 安全审计 pnpm peers check # 报告 lockfile 中未满足/缺失的 peer 依赖 pnpm view <pkg> [field] # 查看 registry 元数据（别名：info、show） pnpm whoami pnpm rebuild # 重建原生模块 pnpm import # 从 npm/yarn lockfile 生成 pnpm-lock.yaml pnpm dedupe # 去重

其中pnpm peers check在 v12 中承担了原--resolution-only的职责，是 CI 中检查 peer 依赖的推荐手段。pnpm import支持从package-lock.json、yarn.lock、npm-shrinkwrap.json转换（见 best-practices-migration.md）。

十一、发布命令

pnpm pack pnpm publish -r --no-git-checks # 递归发布全部包，跳过 git 检查 pnpm version patch|minor|major|2.0.0 # 提升版本，并创建 commit + tag pnpm version prerelease --preid beta pnpm deprecate <pkg>@<range> "message" pnpm dist-tag add <pkg>@<version> <tag> pnpm unpublish <pkg>@<version> # 不推荐；优先用 deprecate pnpm sbom --sbom-format cyclonedx # 生成 SBOM：cyclonedx (1.7) | spdx (2.3) pnpm stage publish ... # 分阶段发布（推迟 2FA 校验）

十二、原生发布管理（v11.13+）

pnpm 可以不借助外部工具完成 workspace 版本与发布，分为两半：

1. 开发过程中用pnpm change记录变更意图——在.changeset/下生成 markdown 文件（changesets 格式），写明受影响包、bump 类型与 changelog 摘要；
2. 发布时用pnpm version -r消费待处理的意图：bump 版本、向依赖者传播、写 changelog，并把消费记录写入已提交的 ledger。

pnpm change # 交互式记录变更意图（写入 .changeset/） pnpm change --bump patch --summary "Fix crash" @ex/core # 非交互（适合脚本） pnpm change status # 查看待处理意图 + 发布计划 pnpm change check # 校验已提交版本 vs epics/fixed groups（CI 用） pnpm version -r [--dry-run] # 消费意图：bump、changelog、ledger（不创建 git tag） pnpm lane <name> --filter <p> # 将包移动到某个发布 lane（--filter 必填）

--bump接受none|patch|minor|major（none表示显式"不发布"）；pnpm version -r不会创建 git commit/tag（多包多版本场景），需自行提交后再pnpm publish -r。lane 用于并行发布轨道（如alpha线发布X.Y.Z-alpha.N预发布版），epics 则将成员包的大版本约束在 lead 包的大版本 ×100 的区间内。完整的配置（versioning.fixed/ignore/maxBump/lanes/epics/changelog）与 ledger 语义见 features-versioning.md。

十三、任务编排与流水线

pnpm -r run <script> # 运行任务图（配置见 features-task-orchestration） pnpm -r run --dry-run build # 只查看任务图（稳定拓扑序，不真正执行） pnpm tasks status # 查看各并发组中运行/等待中的任务（v12.6） pnpm pipeline [name] # 缓存式 CI 风格运行（v12.4，实验性）

pnpm -r run调度的是一个 workspace 任务图：任务是<project>#<script>，当所有dependsOn的任务成功后该任务才就绪，就绪任务在--workspace-concurrency限制下运行。任务依赖在pnpm-workspace.yaml的tasks中声明（^build表示"每个 workspace 依赖的 build"；未配置的任务默认等同dependsOn: ['^build']）。v12.5+ 支持跨进程的并发组（concurrencyGroups）与优先级（priority），v12.4+ 的pnpm pipeline则提供冻结安装 + 受影响项目任务图 + 结果缓存的 CI 式运行。循环依赖会以ERR_PNPM_TASK_CYCLE失败；--no-sort与--parallel会忽略tasks声明。完整机制与配置见 features-task-orchestration.md。

十四、缓存（registry 元数据）

pnpm cache path pnpm cache prune pnpm cache view <pkg>

cache命令族（v12 新增）管理的是registry 元数据缓存，与内容寻址的store不同——store存包内容，cache存元数据。

十五、维护与版本管理

pnpm self-update [<version>] # 更新 packageManager 固定版本，或全局安装 pnpm with current install # 用特定 pnpm 版本执行单条命令 pnpm with 11.0.0 install pnpm approve-builds [--all] # 审查依赖构建脚本（写入 allowBuilds）

pnpm with允许在项目固定的版本之外临时指定 pnpm 版本执行命令；pnpm approve-builds则是供应链安全模型（allowBuilds映射）的交互式入口。

十六、常用 Flags

pnpm install --ignore-scripts pnpm install --prefer-offline pnpm install --prod # -P，省略 devDependencies pnpm install --no-optional pnpm install --strict-peer-dependencies

其余常用组合还包括--frozen-lockfile、--offline、--filter等，均在前文各节出现。这些 flag 的完整行为可结合 core-config.md 中的pnpm-workspace.yaml配置（如strictPeerDependencies、autoInstallPeers）理解。

十七、关键要点速查

• pnpm ci= clean + frozen 安装；CI 自动启用 frozen-lockfile。
• dlx/pnpx是pnx的别名；全局安装现在是按包隔离的（逗号分隔可共享一个组）。
• pnpm link只接受路径；全局 bin 用pnpm add -g .。
• 用pnpm runtime set管理 Node/Deno/Bun；安装时用--no-runtime跳过。
• 发布/registry 命令：version、view、whoami、deprecate、dist-tag、unpublish、sbom、stage。
• v12 新增：原生发布（change、version -r、lane）、任务检查（tasks status）、pipeline、shim、cache命令；pnx可运行其他包管理器/运行时。

本指南为 skills/pnpm 技能集中的 CLI 参考（core-cli.md）的完整展开，其余配置、store、workspace、供应链安全与任务编排等主题可继续阅读 SKILL.md 中的索引表。

• AI 技能
• 人工智能