脚本

pnpm 如何处理 package.json 的 scripts 字段。

Hidden scripts#

名称以 . 开头的脚本将被隐藏。它们不能通过 pnpm run 直接运行，并且会从 pnpm run 列表中省略。隐藏脚本只能从其他脚本调用。

package.json
{
  "scripts": {
    ".helper": "echo 'I am hidden'",
    "build": "pnpm run .helper && tsc"
  }
}

在这个例子中，pnpm run .helper 会失败，但 pnpm run build 会成功，因为 .helper 是从另一个脚本调用的。

环境变量#

pnpm 在生命周期脚本执行期间设置以下环境变量：

  • npm_package_name: the package name
  • npm_package_version: the package version
  • npm_package_config_*, npm_package_engines_*, npm_package_bin_*: the config, engines, and bin fields of the manifest, one variable per entry (for example, npm_package_config_port). A string bin sets npm_package_bin.
  • npm_package_json: the path to the package's package.json
  • npm_lifecycle_event: the name of the running script (e.g., postinstall)
  • npm_lifecycle_script: the command of the running script
  • npm_node_execpath and NODE: the path to the Node.js executable
  • npm_execpath: the path to the running pnpm
  • npm_config_user_agent: pnpm's user agent string
  • npm_config_node_gyp: the path to the bundled node-gyp, unless the environment already sets it
  • INIT_CWD: the directory where pnpm was started
  • PNPM_SCRIPT_SRC_DIR: the directory of the package whose script runs
  • TMPDIR: node_modules/.tmp in the package, unless unsafePerm is true

注意

Apart from the variables above, pnpm does not set npm_config_* variables from its configuration. Other npm_config_* variables in the environment reach the script unchanged, except auth, scope-registry, and per-registry settings (names starting with _, /, or @, or containing :_).

Processes a script leaves running#

A process that a script or a command run by pnpm exec or pnpm dlx starts and leaves running, such as a daemon, an editor, or a browser opened by the open package, keeps running after pnpm exits. It does so whether the script succeeded or failed, and after Ctrl+C, just as it would if the script ran without pnpm. Closing the terminal ends the processes attached to it, as the operating system always does.

pnpm ends what it started in two cases only:

  • When pnpm itself is killed or crashes while a script runs, for example when a CI job is cancelled. On Windows this ends everything the script started, except a process started with CREATE_BREAKAWAY_FROM_JOB. On Unix it ends the scripts that run in a process group of their own, which is every script of a parallel run and every script started without a terminal. A process that leaves its process group, such as a daemon, keeps running.
  • When a script fails in a recursive or parallel run, pnpm stops the scripts of the other packages that are still running, unless --no-bail is set.

Built-in command and script name conflicts#

The following built-in commands prefer user scripts: clean (and its alias purge), setup, deploy, rebuild (and its alias rb), and tasks. 如果你的 package.json 定义了一个具有这些名称之一的脚本，pnpm <name> 将执行该脚本而不是内置命令。

要强制使用内置命令，请使用 pnpm pm <name>。

Lifecycle scripts#

pnpm install runs these scripts of each project in the workspace, in order: preinstall, install, postinstall, preprepare, prepare, and postprepare. With --prod, or when it installs specific packages, it runs only preinstall, install, and postinstall.

For pre and post scripts of other scripts run by pnpm run, see enablePrePostScripts.

pnpm:devPreinstall#

Runs when pnpm install runs in the project itself, including in CI. It does not run when the package is installed as a dependency of another project.

在安装任何依赖项之前运行。

此脚本仅设置在根项目的 package.json 时才执行。