Version: 11.x

pnpm run

别名：run-script

🌐 Aliases: run-script

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

🌐 Runs a script defined in the package's manifest file.

示例

🌐 Examples

假设你在你的 package.json 中配置了一个 watch 脚本，比如这样：

🌐 Let's say you have a watch script configured in your package.json, like so:

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

你现在可以使用 pnpm run watch 来运行该脚本！很简单，对吧？对于那些喜欢节省击键和时间的人，还有一点需要注意的是，所有脚本都会被别名为 pnpm 命令，所以最终 pnpm watch 只是 pnpm run watch 的简写（仅适用于那些名字不与已有 pnpm 命令相同的脚本）。

🌐 You can now run that script by using pnpm run watch! Simple, right? Another thing to note for those that like to save keystrokes and time is that all scripts get aliased in as pnpm commands, so ultimately pnpm watch is just shorthand for pnpm run watch (ONLY for scripts that do not share the same name as already existing pnpm commands).

运行多个脚本

🌐 Running multiple scripts

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

🌐 You may run multiple scripts at the same time by using a regex instead of the script name.

pnpm run "/<regex>/"

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

🌐 Run all scripts that start with watch::

pnpm run "/^watch:.*/"

详情

🌐 Details

除了 shell 预先存在的 PATH 外，pnpm run 在提供给 scripts 的 PATH 中还包括了 node_modules/.bin。这意味着只要你安装了某个包，你就可以像使用常规命令一样在脚本中使用它。例如，如果你安装了 eslint，你可以这样编写脚本：

🌐 In addition to the shell’s pre-existing PATH, pnpm run includes node_modules/.bin in the PATH provided to scripts. This means that so long as you have a package installed, you can use it in a script like a regular command. For example, if you have eslint installed, you can write up a script like so:

"lint": "eslint src --fix"

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

🌐 And even though eslint is not installed globally in your shell, it will run.

对于工作区，<workspace root>/node_modules/.bin 也会被添加到 PATH 中，所以如果在工作区根目录安装了某个工具，它可以在任何工作区包的 scripts 中被调用。

🌐 For workspaces, <workspace root>/node_modules/.bin is also added to the PATH, so if a tool is installed in the workspace root, it may be called in any workspace package's scripts.

环境

🌐 Environment

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

🌐 There are some environment variables that pnpm automatically creates for the executed scripts. These environment variables may be used to get contextual information about the running process.

这些是 pnpm 创建的环境变量：

🌐 These are the environment variables created by pnpm:

npm_command - 包含已执行命令的名称。如果执行的命令是 pnpm run，那么该变量的值将是 "run-script"。

选项

🌐 Options

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

🌐 Any options for the run command should be listed before the script's name. Options listed after the script's name are passed to the executed script.

所有这些都会使用 --silent 选项运行 pnpm CLI：

🌐 All these will run pnpm CLI with the --silent option:

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

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

🌐 Any arguments after the command's name are added to the executed script. So if watch runs webpack --watch, then this command:

pnpm run watch --no-color

将运行：

🌐 will run:

webpack --watch --no-color

--recursive, -r

这会运行每个包的“scripts”对象中的任意命令。如果某个包没有该命令，则会跳过。如果没有任何包拥有该命令，则命令会失败。

🌐 This runs an arbitrary command from each package's "scripts" object. If a package doesn't have the command, it is skipped. If none of the packages have the command, the command fails.

--if-present

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

🌐 You can use the --if-present flag to avoid exiting with a non-zero exit code when the script is undefined. This lets you run potentially undefined scripts without breaking the execution chain.

--parallel

完全无视并发性和拓扑排序，立即在所有匹配的包中运行指定脚本，并使用带前缀的流式输出。这是多包长时间运行过程的首选标志，例如，耗时较长的构建过程。

🌐 Completely disregard concurrency and topological sorting, running a given script immediately in all matching packages with prefixed streaming output. This is the preferred flag for long-running processes over many packages, for instance, a lengthy build process.

--stream

立即输出子进程的流，并在前面加上源包目录前缀。这允许不同包的输出交错显示。

🌐 Stream output from child processes immediately, prefixed with the originating package directory. This allows output from different packages to be interleaved.

--aggregate-output

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

🌐 Aggregate output from child processes that are run in parallel, and only print output when the child process is finished. It makes reading large logs after running pnpm -r <command> with --parallel or with --workspace-concurrency=<number> much easier (especially on CI). Only --reporter=append-only is supported.

--resume-from <package_name>

从特定项目恢复执行。如果你在处理一个大型工作区，并且希望在特定项目上重新开始构建，而无需运行构建顺序中位于它之前的所有项目，这会很有用。

🌐 Resume execution from a particular project. This can be useful if you are working with a large workspace and you want to restart a build at a particular project without running through all of the projects that precede it in the build order.

--report-summary

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

🌐 Record the result of the scripts executions into a pnpm-exec-summary.json file.

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

🌐 An example of a pnpm-exec-summary.json file:

{
  "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'。

🌐 Possible values of status are: 'passed', 'queued', 'running'.

--reporter-hide-prefix

在并行运行的子进程的输出中隐藏工作区前缀，只打印原始输出。如果你在 CI 上运行，并且输出必须采用特定格式而不带任何前缀（例如 GitHub Actions 注释），这会非常有用。仅支持 --reporter=append-only。

🌐 Hide workspace prefix from output from child processes that are run in parallel, and only print the raw output. This can be useful if you are running on CI and the output must be in a specific format without any prefixes (e.g. GitHub Actions annotations). Only --reporter=append-only is supported.

--filter <package_selector>

了解更多关于筛选的信息。

pnpm-workspace.yaml 设置

🌐 pnpm-workspace.yaml settings

enablePrePostScripts

默认：真
类型：布尔

当 true 时，pnpm 会自动运行任何前置/后置脚本。因此运行 pnpm foo 就像运行 pnpm prefoo && pnpm foo && pnpm postfoo 一样。

🌐 When true, pnpm will run any pre/post scripts automatically. So running pnpm foo will be like running pnpm prefoo && pnpm foo && pnpm postfoo.

scriptShell

默认：空
类型：路径

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

🌐 The shell to use for scripts run with the pnpm run command.

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

🌐 For instance, to force usage of Git Bash on Windows:

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

shellEmulator

默认：假
类型：布尔

当 true 时，pnpm 将使用一个基于 JavaScript 的 [类 bash shell] 来执行脚本。

🌐 When true, pnpm will use a JavaScript implementation of a bash-like shell to execute scripts.

此选项简化了跨平台脚本编写。例如，默认情况下，以下脚本将在不符合 POSIX 的系统上失败：

🌐 This option simplifies cross-platform scripting. For instance, by default, the next script will fail on non-POSIX-compliant systems:

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

但是如果将 shellEmulator 设置为 true，它将在所有平台上运行。

🌐 But if the shellEmulator setting is set to true, it will work on all platforms.

note

Node.js 22 或更高版本支持在无需 pnpm 协助的情况下运行脚本。对于上面的示例，你可以使用 node --run test 运行 test 脚本。然而，shellEmulator 选项对此没有影响。依赖 POSIX 功能的脚本需要通过 pnpm run 而不是 node --run 来运行，以便在非 POSIX 兼容的环境中正常工作。

🌐 Node.js 22 or higher supports running scripts without pnpm's assistance. For the example above, you can run the test script with node --run test. However, the shellEmulator option has no effect on this. Scripts that depend on POSIX features are required to be run pnpm run instead of node --run to work in non-POSIX-compliant environments.

示例​

运行多个脚本​

详情​

环境​

选项​

--recursive, -r​

--if-present​

--parallel​

--stream​

--aggregate-output​

--resume-from <package_name>​

--report-summary​

--reporter-hide-prefix​

--filter <package_selector>​

pnpm-workspace.yaml 设置​

enablePrePostScripts​

scriptShell​

shellEmulator​

示例