npm-exec

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

概要

¥Synopsis

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

描述

¥Description

此命令允许你在与通过 npm run 运行类似的上下文中从 npm 包（本地安装或远程获取）运行任意命令。

¥This command allows you to run an arbitrary command from an npm package (either one installed locally, or fetched remotely), in a similar context as running it via npm run.

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

¥Run without positional arguments or --call, this allows you to interactively run commands in the same sort of shell environment that package.json scripts are run. Interactive mode is not supported in CI environments when standard input is a TTY, to prevent hangs.

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

¥Whatever packages are specified by the --package option will be provided in the PATH of the executed command, along with any locally installed package executables. The --package option may be specified multiple times, to execute the supplied command in an environment where all specified packages are available.

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

¥If any requested packages are not present in the local project dependencies, then a prompt is printed, which can be suppressed by providing either --yes or --no. When standard input is not a TTY or a CI environment is detected, --yes is assumed. The requested packages are installed to a folder in the npm cache, which is added to the PATH environment variable in the executed process.

不带说明符的包名称将与本地项目中存在的任何版本匹配。仅当具有与本地依赖完全相同的名称和版本时，带有说明符的包名称才会被视为匹配。

¥Package names provided without a specifier will be matched with whatever version exists in the local project. Package names with a specifier will only be considered a match if they have the exact same name and version as the local dependency.

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

¥If no -c or --call option is provided, then the positional arguments are used to generate the command string. If no --package options are provided, then npm will attempt to determine the executable name from the package specifier provided as the first positional argument according to the following heuristic:

• 如果包在 package.json 的 bin 字段中有一个条目，或者如果所有条目都是同一命令的别名，则将使用该命令。

  ¥If the package has a single entry in its bin field in package.json, or if all entries are aliases of the same command, then that command will be used.

• 如果包有多个 bin 条目，其中一个与 name 字段的无范围部分匹配，则将使用该命令。

  ¥If the package has multiple bin entries, and one of them matches the unscoped portion of the name field, then that command will be used.

• 如果这不会导致恰好一个选项（或者因为没有 bin 条目，或者它们都不匹配包的 name），那么 npm exec 会以错误退出。

  ¥If this does not result in exactly one option (either because there are no bin entries, or none of them match the name of the package), then npm exec exits with an error.

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

¥To run a binary other than the named binary, specify one or more --package options, which will prevent npm from inferring the package from the first command argument.

npx 与 npm exec

¥npx vs npm exec

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

¥When run via the npx binary, all flags and options must be set prior to any positional arguments. When run via npm exec, a double-hyphen -- flag can be used to suppress npm's parsing of switches and options that should be sent to the executed command.

例如：

¥For example:

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

¥In this case, npm will resolve the foo package name, and run the following command:

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

¥Since the --package option comes after the positional arguments, it is treated as an argument to the executed command.

相比之下，由于 npm 的参数解析逻辑，运行这个命令是不同的：

¥In contrast, due to npm's argument parsing logic, running this command is different:

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

¥In this case, npm will parse the --package option first, resolving the @npmcli/foo package. Then, it will execute the following command in that context:

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

¥The double-hyphen character is recommended to explicitly tell npm to stop parsing command line options and switches. The following command would thus be equivalent to the npx command above:

配置

¥Configuration

package

• 默认值：

  ¥Default:

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

  ¥Type: String (can be set multiple times)

为 npm exec 安装的一个或多个包

¥The package or packages to install for npm exec

call

• 默认值：""

  ¥Default: ""

• 类型：字符串

  ¥Type: String

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

¥Optional companion option for npm exec, npx that allows for specifying a custom command to be run along with the installed packages.

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

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.

示例

¥Examples

使用提供的参数在本地依赖中运行 tap 的版本：

¥Run the version of tap in the local dependencies, with the provided arguments:

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

通过指定 --package 选项运行名称与包名称匹配的命令以外的命令：

¥Run a command other than the command whose name matches the package name by specifying a --package option:

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

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

¥Run an arbitrary shell script, in the context of the current project:

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

工作区支持

¥Workspaces support

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

¥You may use the workspace or workspaces configs in order to run an arbitrary command from an npm package (either one installed locally, or fetched remotely) in the context of the specified workspaces. If no positional argument or --call option is provided, it will open an interactive subshell in the context of each of these configured workspaces one at a time.

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

¥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/*" ]
}

使用 workspaces 配置选项 时，你可以在每个已配置工作区的上下文中执行包中的任意命令，在本示例中，我们使用 eslint 来检查每个工作区文件夹中找到的任何 js 文件：

¥You can execute an arbitrary command from a package in the context of each of the configured workspaces when using the workspaces config options, in this example we're using eslint to lint any js file found within each workspace folder:

过滤工作区

¥Filtering workspaces

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

¥It's also possible to execute a command 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 文件夹中运行 eslint 命令。

¥This last command will run the eslint command in both ./packages/a and ./packages/b folders.

与旧 npx 版本的兼容性

¥Compatibility with Older npx Versions

npx 二进制文件在 npm v7.0.0 中被重写，当时不推荐使用独立的 npx 包。npx 使用 npm exec 命令而不是单独的参数解析器和安装过程，具有一些功能以保持与以前版本中接受的参数的向后兼容性。

¥The npx binary was rewritten in npm v7.0.0, and the standalone npx package deprecated at that time. npx uses the npm exec command instead of a separate argument parser and install process, with some affordances to maintain backwards compatibility with the arguments it accepted in previous versions.

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

¥This resulted in some shifts in its functionality:

• 可以提供任何 npm 配置值。

  ¥Any npm config value may be provided.

• 为防止错误输入包名称引起的安全和用户体验问题，npx 会在安装任何内容之前进行提示。使用 -y 或 --yes 选项抑制此提示。

  ¥To prevent security and user-experience problems from mistyping package names, npx prompts before installing anything. Suppress this prompt with the -y or --yes option.

• --no-install 选项已弃用，并将转换为 --no。

  ¥The --no-install option is deprecated, and will be converted to --no.

• Shell 后备功能已被删除，因为它是不可取的。

  ¥Shell fallback functionality is removed, as it is not advisable.

• -p 参数是 npm 中 --parseable 的简写，但 npx 中是 --package 的简写。这是维护的，但仅适用于 npx 可执行文件。

  ¥The -p argument is a shorthand for --parseable in npm, but shorthand for --package in npx. This is maintained, but only for the npx executable.

• --ignore-existing 选项被删除。本地安装的 bin 始终存在于执行的进程 PATH 中。

  ¥The --ignore-existing option is removed. Locally installed bins are always present in the executed process PATH.

• --npm 选项被删除。npx 将始终使用它附带的 npm。

  ¥The --npm option is removed. npx will always use the npm it ships with.

• --node-arg 和 -n 选项被删除。

  ¥The --node-arg and -n options are removed.

• --always-spawn 选项是多余的，因此被删除。

  ¥The --always-spawn option is redundant, and thus removed.

• --shell 选项已替换为 --script-shell，但保留在 npx 可执行文件中以实现向后兼容性。

  ¥The --shell option is replaced with --script-shell, but maintained in the npx executable for backwards compatibility.

关于缓存的说明

¥A note on caching

当使用指定的包名称时，npm cli 会利用其内部包缓存。你可以使用以下内容更改 cli 使用此缓存的方式和时间。有关缓存如何工作的更多信息，请参阅 npm cache。

¥The npm cli utilizes its internal package cache when using the package name specified. You can use the following to change how and when the cli uses this cache. See npm cache for more on how the cache works.

prefer-online

强制检查包的时效性，使 cli 立即查找更新，即使包已经在缓存中。

¥Forces staleness checks for packages, making the cli look for updates immediately even if the package is already in the cache.

prefer-offline

绕过包的时效性检查。仍然会从服务器请求丢失的数据。要强制完全离线模式，请使用 offline。

¥Bypasses staleness checks for packages. Missing data will still be requested from the server. To force full offline mode, use offline.

offline

强制完全离线模式。任何未在本地缓存的包都会导致错误。

¥Forces full offline mode. Any packages not locally cached will result in an error.

工作区

¥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 to selecting all of the nested workspaces)

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

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

workspaces

• 别名：--ws

  ¥Alias: --ws

• 类型：布尔值

  ¥Type: Boolean

• 默认值：false

  ¥Default: false

在当前项目的所有已配置工作区的上下文中运行脚本。

¥Run scripts in the context of all configured workspaces for the current project.

也可以看看

¥See Also

• npm run-script

• npm scripts

• npm test

• npm start

• npm restart

• npm stop

• npm config

• npm workspaces

• npx