目录
npm-exec
选择命令行版本:
目录
概要
¥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 inpackage.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 thename
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), thennpm 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:
$ npx foo@latest bar --package=@npmcli/foo
在这种情况下,npm 将解析 foo
包名,并运行以下命令:
¥In this case, npm will resolve the foo
package name, and run the following command:
$ foo bar --package=@npmcli/foo
由于 --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 exec foo@latest bar --package=@npmcli/foo
在这种情况下,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:
$ foo@latest bar
建议使用双连字符来明确告诉 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:
$ npm exec -- foo@latest bar --package=@npmcli/foo
配置
¥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 thenode_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 theworkspace
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:
npm exec --ws -- eslint ./*.js
过滤工作区
¥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:
npm exec --workspace=a -- eslint ./*.js
也可以多次指定 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:
npm exec -w a -w b -- eslint ./*.js
最后一个命令将在 ./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 thenpx
executable. -
--ignore-existing
选项被删除。本地安装的 bin 始终存在于执行的进程PATH
中。¥The
--ignore-existing
option is removed. Locally installed bins are always present in the executed processPATH
. -
--npm
选项被删除。npx
将始终使用它附带的npm
。¥The
--npm
option is removed.npx
will always use thenpm
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 thenpx
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