# npm run-script

运行任意包脚本

# 概要

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

aliases: run, rum, urn

# 描述

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

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

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

例如：

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

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

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

除了 shell 原有的 PATH 之外，npm run 还将 node_modules/.bin 添加到提供给脚本的 PATH 中。

可以在不使用 node_modules/.bin 前缀的情况下使用本地安装的依赖项提供的任何二进制文件。例如，如果在你的包中有一个 devDependency 在 tap 上，你应该写:

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

代替

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

运行脚本的实际 shell 是平台相关的。默认情况下，在类 unix 系统上是 /bin/sh 命令，在 Windows 上是 cmd.exe 命令。/bin/sh 所引用的实际 shell 也取决于系统。您可以通过 script-shell 配置自定义 shell。

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

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

如果您试图在没有 node_modules 目录的情况下运行脚本，并且失败了，您将得到一个运行 npm install 的警告，以防您忘记了。

# 工作空间的支持

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

给定一个带有配置工作空间的项目，例如:

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

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

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

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

npm test --workspaces

# 过滤工作区

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

npm test --workspace=a

还可以多次指定 workspace 配置，以便在多个工作空间的上下文中运行特定的脚本。当在命令行中为 workspace 配置定义值时，也可以使用 -w 作为速记，例如:

npm test -w a -w b

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

# 配置

# workspace

Default:
Type: String (可以设置多次)

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

workspace 配置的有效值如下:

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

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

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

# workspaces

Default: null
Type: null or Boolean

设置为 true 将在所有配置的工作区中运行该命令。

显式地将此设置为 false 将导致如下命令 install 完全忽略工作空间。当没有显式设置时:

在 node_modules 树上操作的命令 (install, update, etc.) 时，将把工作区链接到 node_modules 文件夹中。做其他事情的命令 (test, exec, publish, etc.) 将在根项目上操作，除非在 workspace 配置中指定了一个或多个工作空间。

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

# include-workspace-root

Default: false
Type: Boolean

当为某个命令启用工作区时，请包含工作区根目录。

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

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

# if-present

Default: false
Type: Boolean

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

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

# ignore-scripts

Default: false
Type: Boolean

如果为 true, npm 不会运行包中指定的 package.json 文件。

注意

如果设置了 ignore-scripts，那些显式地想要运行特定脚本的命令，比如 npm start、npm stop、npm restart、npm test 和 npm run-script 仍然会运行它们想要运行的脚本，但是它们不会运行任何前脚本或后脚本。

# foreground-scripts

Default: false
Type: Boolean

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

注意

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

# script-shell

Default: 在 POSIX 系统上为“/bin/sh”，在 Windows 上为“cmd.exe”
Type: null | String

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

← npm root npm search →