# 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 之后指定的脚本,而不会传递给任何 prepost 脚本。

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

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

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

"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 的警告,以防您忘记了。

# 工作空间的支持

您可以使用 workspaceworkspaces 配置,以便在指定 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.jsonscripts 部分定义的脚本调用 run-script 时,npm 将不会退出并返回错误代码。当需要在脚本出现时运行脚本,并在脚本失败时失败时,可以使用此选项。这是有用的,例如,当运行的脚本可能只适用于其他通用CI设置中的某些构建时。

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

# ignore-scripts

  • Default: false
  • Type: Boolean

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

注意

如果设置了 ignore-scripts,那些显式地想要运行特定脚本的命令,比如 npm startnpm stopnpm restartnpm testnpm 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 execnpm runnpm init <package-spec> 命令一起运行的脚本的 shell。

Last Updated: 4/25/2023, 9:49:29 AM