pnpm run

别名: run-script

运行在软件包清单文件中定义的脚本。

示例#

假如你有个 watch 脚本配置在了 package.json 中，像这样：

"scripts": {
    "watch": "webpack --watch"
}

你现在可以使用 pnpm run watch 运行该脚本！很简单吧？对于那些不喜欢敲键盘而浪费时间的人要注意的另一件事是，所有脚本都会有 pnpm 命令的别名，所以最终 pnpm run watch 的简写是 pnpm watch （仅适用于那些不与已有的 pnpm 命令相同名字的脚本）。

运行多个脚本#

你可以使用正则表达式来替代脚本名称从而同时运行多个脚本。

pnpm run "/<regex>/"

运行所有以 watch: 开头的脚本。

pnpm run "/^watch:/"

The selector must be written as a regular expression literal (that is, wrapped in slashes) and quoted, so the shell does not mangle it. 普通字符串始终被视为字面意义上的脚本名称；若脚本名称与该参数完全匹配，则其优先级高于正则表达式匹配。

匹配不受锚定，因此 "/build:.*/" 也会匹配 prebuild:web。当你需要精确前缀时，请用 ^ 和 $ 锚定模式。

匹配到的脚本按字典序运行，因此无论脚本在 package.json 中的顺序如何，选择结果都是确定的。若要严格逐个运行，请添加 --sequential。

不支持正则表达式标志：pnpm run "/^build:.*/i" 会以 ERR_PNPM_UNSUPPORTED_SCRIPT_COMMAND_FORMAT 失败。

详情#

In addition to the shell's pre-existing PATH, pnpm run includes node_modules/.bin in the PATH provided to scripts. 这意味着，只要你安装了一个包，你就可以像常规命令一样在脚本中使用它。例如，如果你已经安装了 eslint，你可以这样写一个脚本：

"lint": "eslint src --fix"

即使 eslint 没有在你的 shell 中全局安装，它也会运行。

对于工作空间， <workspace root>/node_modules/.bin 也会被添加到到 PATH 中，因此如果在工作空间根目录中安装了工具，则可以在工作空间中任何软件包的 scripts 中调用它。

运行环境#

pnpm 会自动为执行的脚本创建一些环境变量。这些环境变量可用于获取有关正在运行的进程的上下文信息。

以下是 pnpm 会创建的环境变量：

• npm_command - 包含已执行命令的名称。如果执行的命令是 pnpm run，那么这个变量的值就是“run-script”。

配置项#

run 命令的选项都应被列在脚本名称之前。脚本名称后列出的options将传递给执行的脚本。

例如下面这些都将使用 --silent 选项运行 pnpm CLI：

pnpm run --silent watch
pnpm --silent run watch
pnpm --silent watch

脚本名称后的任何参数都将添加到执行的脚本中。所以如果 watch 运行 webpack --watch，那么这个命令：

pnpm run watch --no-color

将运行：

webpack --watch --no-color

--recursive, -r#

这会从每个包的 "scripts" 字段中运行任意一个命令。如果包没有该命令，则会跳过该命令。如果所有包都没有该命令，则该命令将失败。

By default, recursive runs use a dependency-aware task graph. Configure relationships between scripts with the tasks setting. --no-sort, and --parallel which implies it, remove that ordering and ignore the tasks declarations along with it.

--if-present#

可以使用 --if-present 标志来避免在脚本未定义时以非零退出码退出。这使你可以在不中断执行链的情况下运行可能未定义的脚本。

--no-bail#

即使其中一个匹配的脚本失败，也要继续运行其余脚本。如果任何脚本执行失败，该命令仍会以非零退出码退出。

--parallel#

完全忽略并发和拓扑排序，在所有匹配的包中立即运行给定的脚本 并输出前缀流。对于许多包中长时间运行的进程，这是首选标志，例如漫长的构建进程。

--sequential, -s#

添加于: v11.14.0

逐个运行选定的脚本。 This forces --workspace-concurrency to 1, so scripts matched by a regex selector never overlap, neither across workspace packages nor within a single package.

pnpm run --sequential "/^build:.*/"

在递归运行模式下，该操作会对工作区内各项目之间以及每个项目内部的脚本进行序列化处理。 --sequential 优先于 --parallel：只要设置了它，并发度就固定为 1，与两个标志出现的先后顺序无关。

--workspace-concurrency#

Set the maximum number of workspace tasks to run simultaneously. See pnpm recursive --workspace-concurrency for defaults and how zero and negative values are interpreted.

--stream#

立即从子进程流式传输输出，并以原始包目录为前缀。这使得不同包的输出可以交错。

--aggregate-output#

聚合并行运行的子进程的输出，并且仅在子进程完成时打印输出。它使在运行 pnpm -r <command> 时使用 --parallel 或 --workspace-concurrency=<number> 后读取大日志更容易（尤其是在 CI 上）。仅支持 --reporter=append-only。

--resume-from <package_name>#

Resume at the named package's requested task. pnpm skips the tasks a matching record of the previous run says already passed; without such a record it omits the task's transitive dependencies instead, treating them as completed. Either way it still runs the task itself, its dependents, and unrelated tasks in the selected graph. See Workspace task orchestration.

--dry-run#

Resolve a recursive run's task graph without running scripts. The plain output is one stable topological ordering, not a prediction of the order in which independent tasks will be dispatched.

pnpm -r run --dry-run build

--dry-run is only supported for recursive runs.

--json#

With --dry-run, print the resolved tasks and their dependency edges as JSON. See Inspect the task graph for the schema and an example.

--report-summary#

将脚本执行的结果记录到 pnpm-exec-summary.json 文件中。

pnpm-exec-summary.json 文件的示例：

{
  "executionStatus": {
    "/Users/zoltan/src/pnpm/pnpm/cli/command": {
      "status": "passed",
      "duration": 1861.143042
    },
    "/Users/zoltan/src/pnpm/pnpm/cli/common-cli-options-help": {
      "status": "passed",
      "duration": 1865.914958
    }
  }
}

status 的可能值为：“passed”、“queued”、“running”。

--reporter-hide-prefix#

从并行运行的子进程的输出中隐藏工作空间前缀，并且仅打印原始输出。如果你在 CI 上运行并且输出必须采用特定格式而没有任何前缀（例如 GitHub Actions 注释），则此功能很有用。仅支持 --reporter=append-only。

--filter <package_selector>#

阅读更多有关过滤的内容。

pnpm-workspace.yaml 设置#

The tasks setting configures dependency relationships and per-task concurrency limits for recursive runs.

enablePrePostScripts#

• 默认值：true
• 类型：Boolean

当 true 时，pnpm 将自动运行任何前/后脚本。因此运行 pnpm foo 将类似于运行 pnpm prefoo pnpm foo pnpm postfoo。

scriptShell#

• 默认值： null
• 类型：路径

使用 pnpm run 命令运行脚本所使用的 shell。

例如，在 Windows 系统上强制使用 Git Bash：

pnpm config set scriptShell "C:\Program Files\git\bin\bash.exe"

Since v11.26.0, a relative path in pnpm-workspace.yaml resolves from the workspace root, including for scripts that run in a nested package. A bare command name such as bash is still looked up on PATH.

shellEmulator#

• 默认值： false
• 类型：Boolean

当为 true 时，pnpm 将使用 [类 bash shell][bash-like shell] 的 JavaScript 实现来 执行脚本。

该选项简化了跨平台运行脚本。例如，默认情况下，下述脚本将在非 POSIX 标准兼容系统下运行失败：

"scripts": {
  "test": "NODE_ENV=test node test.js"
}

但是，如果 shellEmulator 设置为 true，它将适用于所有平台。

Since v11.28.1, a configured non-empty scriptShell wins over shellEmulator for pnpm run and lifecycle scripts. The emulator runs only when scriptShell is unset or empty.