npx

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

概要

¥Synopsis

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

描述

¥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.

--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.

如果本地项目依赖中不存在任何请求的包，则将它们安装到 npm 缓存中的文件夹中，该文件夹在执行过程中添加到 PATH 环境变量中。打印一个提示（可以通过提供 --yes 或 --no 来抑制）。

¥If any requested packages are not present in the local project dependencies, then they are installed to a folder in the npm cache, which is added to the PATH environment variable in the executed process. A prompt is printed (which can be suppressed by providing either --yes or --no).

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

¥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:

示例

¥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"'

与旧 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 选项已被删除。使用 NODE_OPTIONS 代替：e.g., NODE_OPTIONS="--trace-warnings --trace-exit" npx foo --random=true

  ¥The --node-arg and -n options have been removed. Use NODE_OPTIONS instead: e.g., NODE_OPTIONS="--trace-warnings --trace-exit" npx foo --random=true

• --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.

也可以看看

¥See Also

• npm run-script

• npm scripts

• npm test

• npm start

• npm restart

• npm stop

• npm config

• npm exec