npm-run-script

运行任意包脚本

概要

¥Synopsis

npm run-script <command> [-- <args>]

aliases: run, rum, urn

描述

¥Description

这会从包的 "scripts" 对象运行任意命令。如果没有提供 "command"，它将列出可用的脚本。

¥This runs an arbitrary command from a package's "scripts" object. If no "command" is provided, it will list the available scripts.

run[-script] 由 test、start、restart 和 stop 命令使用，但也可以直接调用。当包中的脚本被打印出来时，它们被分为生命周期（测试、启动、重启）和直接运行的脚本。

¥run[-script] is used by the test, start, restart, and stop commands, but can be called directly, as well. When the scripts in the package are printed out, they're separated into lifecycle (test, start, restart) and directly-run scripts.

任何位置参数都会传递给指定的脚本。使用 -- 传递以 - 为前缀的标志和选项，否则它们会被 npm 解析。

¥Any positional arguments are passed to the specified script. Use -- to pass --prefixed flags and options which would otherwise be parsed by npm.

例如：

¥For example:

npm run test -- --grep="pattern"

参数只会传递给 npm run 之后指定的脚本，而不是任何 pre 或 post 脚本。

¥The arguments will only be passed to the script specified after npm run and not to any pre or post script.

env 脚本是一个特殊的内置命令，可用于列出脚本在运行时可用的环境变量。如果你的包中定义了 "env" 命令，它将优先于内置命令。

¥The env script is a special built-in command that can be used to list environment variables that will be available to the script at runtime. If an "env" command is defined in your package, it will take precedence over the built-in.

除了 shell 预先存在的 PATH 之外，npm run 还将 node_modules/.bin 添加到提供给脚本的 PATH 中。本地安装的依赖提供的任何二进制文件都可以在没有 node_modules/.bin 前缀的情况下使用。例如，如果你的包中 tap 上有一个 devDependency，你应该写：

¥In addition to the shell's pre-existing PATH, npm run adds node_modules/.bin to the PATH provided to scripts. Any binaries provided by locally-installed dependencies can be used without the node_modules/.bin prefix. For example, if there is a devDependency on tap in your package, you should write:

"scripts": {"test": "tap test/*.js"}

代替

¥instead of

"scripts": {"test": "node_modules/.bin/tap test/*.js"}

运行脚本的实际 shell 取决于平台。默认情况下，在类 Unix 系统上是 /bin/sh 命令，在 Windows 上是 cmd.exe。/bin/sh 所指的实际外壳也取决于系统。你可以使用 script-shell 配置自定义 shell。

¥The actual shell your script is run within is platform dependent. By default, on Unix-like systems it is the /bin/sh command, on Windows it is cmd.exe. The actual shell referred to by /bin/sh also depends on the system. You can customize the shell with the script-shell configuration.

脚本从包文件夹的根目录运行，无论调用 npm run 时当前工作目录是什么。如果你希望脚本根据你所在的子目录使用不同的行为，你可以使用 INIT_CWD 环境变量，它包含你在运行 npm run 时所在的完整路径。

¥Scripts are run from the root of the package folder, regardless of what the current working directory is when npm run is called. If you want your script to use different behavior based on what subdirectory you're in, you can use the INIT_CWD environment variable, which holds the full path you were in when you ran npm run.

npm run 将 NODE 环境变量设置为执行 npm 的 node 可执行文件。

¥npm run sets the NODE environment variable to the node executable with which npm is executed.

如果你尝试在没有 node_modules 目录的情况下运行脚本但它失败了，你将收到运行 npm install 的警告，以防你忘记了。

¥If you try to run a script without having a node_modules directory and it fails, you will be given a warning to run npm install, just in case you've forgotten.

工作区支持

¥Workspaces support

你可以使用 workspace 或 workspaces 配置，以便在指定工作区的上下文中从包的 "scripts" 对象运行任意命令。如果未提供 "command"，它将列出每个已配置工作区的可用脚本。

¥You may use the workspace or workspaces configs in order to run an arbitrary command from a package's "scripts" object in the context of the specified workspaces. If no "command" is provided, it will list the available scripts for each of these configured workspaces.

给定一个具有已配置工作区的项目，例如：

¥Given a project with configured workspaces, e.g:

.
+-- package.json
`-- packages
   +-- a
   |   `-- package.json
   +-- b
   |   `-- package.json
   `-- c
       `-- package.json

假设工作区配置在根级别 package.json 文件中正确设置。例如：

¥Assuming the workspace configuration is properly set up at the root level package.json file. e.g:

{
    "workspaces": [ "./packages/*" ]
}

每个已配置的工作区都有一个已配置的 test 脚本，我们可以使用 workspaces 配置在所有工作区中运行测试：

¥And that each of the configured workspaces has a configured test script, we can run tests in all of them using the workspaces config:

过滤工作区

¥Filtering workspaces

也可以使用 workspace 配置以及名称或目录路径在单个工作区中运行脚本：

¥It's also possible to run a script in a single workspace using the workspace config along with a name or directory path:

也可以多次指定 workspace 配置，以便在多个工作区的上下文中运行特定脚本。在命令行中为 workspace 配置定义值时，也可以使用 -w 作为简写，例如：

¥The workspace config can also be specified multiple times in order to run a specific script in the context of multiple workspaces. When defining values for the workspace config in the command line, it also possible to use -w as a shorthand, e.g:

最后一条命令将在 ./packages/a 和 ./packages/b 包中运行 test。

¥This last command will run test in both ./packages/a and ./packages/b packages.

配置

¥Configuration

workspace

• 默认值：

  ¥Default:

• 类型：字符串（可以设置多次）

  ¥Type: String (can be set multiple times)

启用在当前项目的已配置工作区的上下文中运行命令，同时通过仅运行此配置选项定义的工作区进行过滤。

¥Enable running a command in the context of the configured workspaces of the current project while filtering by running only the workspaces defined by this configuration option.

workspace 配置的有效值为：

¥Valid values for the workspace config are either:

• 工作区名称

  ¥Workspace names

• 工作区目录的路径

  ¥Path to a workspace directory

• 父工作区目录的路径（将导致选择该文件夹中的所有工作区）

  ¥Path to a parent workspace directory (will result in selecting all workspaces within that folder)

为 npm init 命令设置时，可以将其设置为尚不存在的工作区的文件夹，以创建文件夹并将其设置为项目中的全新工作区。

¥When set for the npm init command, this may be set to the folder of a workspace which does not yet exist, to create the folder and set it up as a brand new workspace within the project.

此值不会导出到子进程的环境中。

¥This value is not exported to the environment for child processes.

workspaces

• 默认值：null

  ¥Default: null

• 类型：空值或布尔值

  ¥Type: null or Boolean

设置为 true 可在所有已配置工作区的上下文中运行该命令。

¥Set to true to run the command in the context of all configured workspaces.

显式将此设置为 false 将导致像 install 这样的命令完全忽略工作区。未明确设置时：

¥Explicitly setting this to false will cause commands like install to ignore workspaces altogether. When not set explicitly:

• 在 node_modules 树上运行的命令（安装、更新等）会将工作区链接到 node_modules 文件夹。* 执行其他操作（测试、执行、发布等）的命令将在根项目上运行，除非在 workspace 配置中指定了一个或多个工作区。

  ¥Commands that operate on the node_modules tree (install, update, etc.) will link workspaces into the node_modules folder. - Commands that do other things (test, exec, publish, etc.) will operate on the root project, unless one or more workspaces are specified in the workspace config.

此值不会导出到子进程的环境中。

¥This value is not exported to the environment for child processes.

include-workspace-root

• 默认值：false

  ¥Default: false

• 类型：布尔值

  ¥Type: Boolean

为命令启用工作区时包括工作区根。

¥Include the workspace root when workspaces are enabled for a command.

当为 false 时，通过 workspace 配置指定单个工作区，或通过 workspaces 标志指定所有工作区，将导致 npm 仅在指定的工作区上运行，而不是在根项目上运行。

¥When false, specifying individual workspaces via the workspace config, or all workspaces via the workspaces flag, will cause npm to operate only on the specified workspaces, and not on the root project.

此值不会导出到子进程的环境中。

¥This value is not exported to the environment for child processes.

if-present

• 默认值：false

  ¥Default: false

• 类型：布尔值

  ¥Type: Boolean

如果为 true，当为 package.json 的 scripts 部分中未定义的脚本调用 run-script 时，npm 将不会退出并返回错误代码。当需要在脚本存在时选择性地运行脚本并在脚本失败时运行失败时，可以使用此选项。这很有用，例如，在运行可能仅适用于其他通用 CI 设置中的某些构建的脚本时。

¥If true, npm will not exit with an error code when run-script is invoked for a script that isn't defined in the scripts section of package.json. This option can be used when it's desirable to optionally run a script when it's present and fail if the script fails. This is useful, for example, when running scripts that may only apply for some builds in an otherwise generic CI setup.

此值不会导出到子进程的环境中。

¥This value is not exported to the environment for child processes.

ignore-scripts

• 默认值：false

  ¥Default: false

• 类型：布尔值

  ¥Type: Boolean

如果为 true，npm 不会运行 package.json 文件中指定的脚本。

¥If true, npm does not run scripts specified in package.json files.

请注意，如果设置了 ignore-scripts，则明确旨在运行特定脚本的命令（例如 npm start、npm stop、npm restart、npm test 和 npm run-script）仍将运行其预期的脚本，但它们不会运行任何前置或后置脚本。

¥Note that commands explicitly intended to run a particular script, such as npm start, npm stop, npm restart, npm test, and npm run-script will still run their intended script if ignore-scripts is set, but they will not run any pre- or post-scripts.

foreground-scripts

• 默认值：false

  ¥Default: false

• 类型：布尔值

  ¥Type: Boolean

在前台进程中运行已安装包的所有构建脚本（即 preinstall、install 和 postinstall）脚本，与主 npm 进程共享标准输入、输出和错误。

¥Run all build scripts (ie, preinstall, install, and postinstall) scripts for installed packages in the foreground process, sharing standard input, output, and error with the main npm process.

请注意，这通常会使安装运行速度变慢，并且噪音更大，但对调试很有用。

¥Note that this will generally make installs run slower, and be much noisier, but can be useful for debugging.

script-shell

• 默认值：'/bin/sh' 在 POSIX 系统上，'cmd.exe' 在 Windows 上

  ¥Default: '/bin/sh' on POSIX systems, 'cmd.exe' on Windows

• 类型：空值或字符串

  ¥Type: null or String

用于脚本的 shell 与 npm exec、npm run 和 npm init <package-spec> 命令一起运行。

¥The shell to use for scripts run with the npm exec, npm run and npm init <package-spec> commands.

也可以看看

¥See Also

• npm scripts

• npm test

• npm start

• npm restart

• npm stop

• npm config

• npm workspaces