npm-exec

从本地或远程 npm 包运行命令

选择 CLI 版本

概述

npm exec -- <pkg>[@<version>] [args...]
npm exec --package=<pkg>[@<version>] -- <cmd> [args...]
npm exec -c '<cmd> [args...]'
npm exec --package=foo -c '<cmd> [args...]'

alias: x

描述

此命令允许您从 npm 包（本地安装的或远程获取的）运行任意命令，类似于通过 npm run 运行该命令。

在没有位置参数或 --call 的情况下运行，这允许您在与 package.json 脚本运行相同的 shell 环境中交互式地运行命令。当标准输入是 TTY 时，在 CI 环境中不支持交互模式，以防止挂起。

--package 选项指定的任何包都将在执行命令的 PATH 中提供，以及任何本地安装的包可执行文件。可以多次指定 --package 选项，以在所有指定包都可用的环境中执行提供的命令。

如果本地项目依赖项中不存在任何请求的包，则会打印提示，可以通过提供 --yes 或 --no 来抑制提示。当标准输入不是 TTY 或检测到 CI 环境时，将假定为 --yes。请求的包将安装到 npm 缓存中的文件夹中，该文件夹将添加到执行过程中 PATH 环境变量中。

提供的没有指定符的包名将与本地项目中存在的任何版本匹配。具有指定符的包名只有在它们的名称和版本与本地依赖项完全相同的情况下才会被视为匹配。

如果没有提供 -c 或 --call 选项，则位置参数将用于生成命令字符串。如果没有提供 --package 选项，则 npm 将尝试根据以下启发式方法从作为第一个位置参数提供的包规范符中确定可执行文件名称

如果包的 package.json 中的 bin 字段中只有一个条目，或者所有条目都是同一个命令的别名，则将使用该命令。
如果包有多个 bin 条目，并且其中一个条目与 name 字段的非作用域部分匹配，则将使用该命令。
如果这没有导致恰好一个选项（要么是因为没有 bin 条目，要么是因为没有一个条目与包的 name 匹配），则 npm exec 退出并报错。

要运行除了命名二进制文件之外的二进制文件，请指定一个或多个 --package 选项，这将阻止 npm 从第一个命令参数中推断出包。

`npx` 与 `npm exec`

通过 npx 二进制文件运行时，所有标志和选项必须在任何位置参数之前设置。通过 npm exec 运行时，可以使用双连字符 -- 标志来抑制 npm 对应发送到执行命令的开关和选项的解析。

例如

$ npx foo@latest bar --package=@npmcli/foo

在这种情况下，npm 将解析 foo 包名，并运行以下命令

$ foo bar --package=@npmcli/foo

由于 --package 选项位于位置参数之后，因此它被视为执行命令的参数。

相反，由于 npm 的参数解析逻辑，运行此命令是不同的

$ npm exec foo@latest bar --package=@npmcli/foo

在这种情况下，npm 将首先解析 --package 选项，解析 @npmcli/foo 包。然后，它将在该上下文中执行以下命令

$ foo@latest bar

建议使用双连字符来明确告诉 npm 停止解析命令行选项和开关。因此，以下命令等效于上面的 npx 命令

$ npm exec -- foo@latest bar --package=@npmcli/foo

配置

`包`

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

要为 npm exec 安装的包或包

`调用`

默认：""
类型：字符串

npm exec、npx 的可选配套选项，允许指定要与安装的包一起运行的自定义命令。

npm exec --package yo --package generator-node --call "yo node"

`工作区`

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

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

workspace 配置的有效值为：

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

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

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

`工作区`

默认值：null
类型：null 或布尔值

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

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

在 node_modules 树（install、update 等）上操作的命令会将工作区链接到 node_modules 文件夹中。 - 执行其他操作（test、exec、publish 等）的命令将作用于根项目，*除非* workspace 配置中指定了一个或多个工作区。

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

`include-workspace-root`

默认值：false
类型：布尔值

在为命令启用工作区时，包括工作区根目录。

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

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

示例

运行本地依赖项中的 tap 版本，并使用提供的参数。

$ npm exec -- tap --bail test/foo.js
$ npx tap --bail test/foo.js

通过指定 --package 选项来运行 *除* 与包名称匹配的命令名称之外的命令。

$ npm exec --package=foo -- bar --bar-argument
# ~ or ~
$ npx --package=foo bar --bar-argument

在当前项目上下文中运行任意 shell 脚本。

$ npm x -c 'eslint && say "hooray, lint passed"'
$ npx -c 'eslint && say "hooray, lint passed"'

工作区支持

您可以使用 workspace 或 workspaces 配置以在指定的工作区上下文中运行来自 npm 包的任意命令（本地安装的包或远程获取的包）。如果未提供位置参数或 --call 选项，它将依次在这些配置的工作区中的每个工作区的上下文中打开一个交互式子 shell。

假设一个具有配置工作区的项目，例如

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

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

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

当使用 workspaces 配置选项时，您可以从包中执行任意命令，在每个配置的工作区上下文中执行，在此示例中，我们使用 **eslint** 来 lint 在每个工作区文件夹中找到的任何 js 文件

npm exec --ws -- eslint ./*.js

过滤工作区

也可以使用 workspace 配置以及名称或目录路径在单个工作区中执行命令

npm exec --workspace=a -- eslint ./*.js

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

npm exec -w a -w b -- eslint ./*.js

最后一个命令将在 ./packages/a 和 ./packages/b 文件夹中运行 eslint 命令。

与旧版 npx 的兼容性

npx 二进制文件在 npm v7.0.0 中重写，并且独立的 npx 包在那个时候被弃用。 npx 使用 npm exec 命令，而不是单独的参数解析器和安装过程，并提供了一些便利来保持与先前版本中接受的参数的向后兼容性。

这导致其功能发生了一些变化

可以提供任何 npm 配置值。
为了防止因错误输入包名称而导致的安全和用户体验问题， npx 在安装任何内容之前提示。使用 -y 或 --yes 选项来抑制此提示。
--no-install 选项已弃用，并将转换为 --no 。
shell 回退功能已移除，因为不建议使用。
-p 参数是 npm 中 --parseable 的简写，但在 npx 中是 --package 的简写。这是保留的，但仅限于 npx 可执行文件。
--ignore-existing 选项已移除。本地安装的 bin 始终存在于执行的进程 PATH 中。
--npm 选项已移除。 npx 将始终使用它附带的 npm 。
--node-arg 和 -n 选项已移除。
--always-spawn 选项是多余的，因此已移除。
--shell 选项已替换为 --script-shell ，但在 npx 可执行文件中为了向后兼容性而保留。