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 執行指令相同的殼層環境中互動式執行指令。當標準輸入為 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

設定

`package`

預設值
類型：字串（可以設定多次）

要安裝 npm exec 的套件或套件組

`call`

預設值：""
類型：字串

用於 npm exec、npx 的選用伴隨選項，允許指定要與已安裝套件一起執行的自訂命令。

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

`workspace`

預設值
類型：字串（可以設定多次）

啟用在當前專案設定的工作空間內容中執行命令，同時透過僅執行此組態選項所定義的工作空間來進行篩選。

workspace 組態的有效值為

工作空間名稱
工作空間目錄的路徑
父工作空間目錄的路徑（將選取該資料夾中的所有工作空間）

針對 npm init 命令設定時，可以設定為尚未存在的工作空間資料夾，以建立資料夾並將其設定為專案中的全新工作空間。

此值不會匯出至子程式的環境。

`workspaces`

預設值：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 來檢查每個工作區資料夾中找到的任何 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 版本相容

在 npm v7.0.0 中重新編寫了 npx 二進位檔，並在當時棄用獨立的 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 可執行檔中，以維持向後相容性。