針對 .NET 工具使用問題進行疑難解答

嘗試安裝或執行 .NET 工具時，可能會遇到問題，這可能是全域工具或本機工具。 本文說明常見的根本原因和一些可能的解決方案。

安裝的 .NET 工具無法執行

當 .NET 工具無法執行時，您很可能遇到下列其中一個問題：

• 找不到工具的可執行檔。
• 找不到正確的 .NET 運行時間版本。

找不到可執行檔

如果找不到可執行檔，您會看到類似下列的訊息：

Could not execute because the specified command or file was not found.
Possible reasons for this include:
  * You misspelled a built-in dotnet command.
  * You intended to execute a .NET program, but dotnet-xyz does not exist.
  * You intended to run a global tool, but a dotnet-prefixed executable with this name could not be found on the PATH.

可執行文件的名稱會決定您叫用工具的方式。 下表描述格式：

可執行檔案名稱格式	調用格式
dotnet-<toolName>.exe	dotnet <toolName>
<toolName>.exe	<toolName>

全域工具

全域工具可以安裝在預設目錄或特定位置。 預設目錄為：

操作系統	路徑
Linux/macOS	$HOME/.dotnet/tools
窗戶	%USERPROFILE%\.dotnet\tools

如果您嘗試執行全域工具，請檢查您電腦上的 PATH 環境變數是否包含您安裝全域工具的路徑，且可執行檔位於該路徑中。

.NET CLI 會嘗試在其第一次使用時，將預設位置新增至PATH環境變數。 不過，在某些情況下，位置可能不會自動新增至PATH：

• 如果您使用 Linux，且已使用 .tar.gz 檔案來安裝 .NET SDK，而不是 apt-get 或 rpm。
• 如果您使用macOS 10.15 “Catalina” 或更新版本。
• 如果您使用 macOS 10.14 “Mojave” 或舊版，而且您已使用 .tar.gz 檔案來安裝 .NET SDK，而不是 .pkg。
• 如果您已安裝 .NET Core 3.0 SDK，且已將 DOTNET_ADD_GLOBAL_TOOLS_TO_PATH 環境變數設定為 false。
• 如果您已安裝 .NET Core 2.2 SDK 或舊版，且已將 DOTNET_SKIP_FIRST_TIME_EXPERIENCE 環境變數設定為 true。

在這些案例中，或如果您在安裝 dotnet 工具 時指定了 --tool-path 選項，則您電腦上的 PATH 環境變數不會自動包含您安裝全域工具的路徑。 在此情況下，請使用殼層為更新環境變數提供的任何方法，將工具位置（例如，$HOME/.dotnet/tools）附加至 PATH 環境變數。 如需詳細資訊，請參閱 .NET 工具。

本機工具

如果您嘗試執行本機工具，請確認目前目錄中或任何其父目錄中有稱為 dotnet-tools.json 的指令清單檔。 此檔案也可以位於名為 .config 項目資料夾階層中任何位置的資料夾底下，而不是根資料夾。 如果 dotnet-tools.json 存在，請打開它並檢查您要執行的工具。 如果檔案中沒有包含 "isRoot": true的條目，則也需要在更高層的檔案階層中查找其他工具指令清單檔。

如果您嘗試執行以指定路徑安裝的 .NET 工具，則必須在使用此工具時包含該路徑。 以下是使用具有工具路徑的已安裝工具的範例：

..\<toolDirectory>\dotnet-<toolName>

找不到運行時間

.NET 工具 與架構相關的應用程式，這表示它們依賴您計算機上安裝的 .NET 運行時間。 如果找不到預期的運行時間，則會遵循一般 .NET 運行時間向前復原規則，例如：

• 應用程式會升級到指定的主要和次要版本的最新修補程式版本。
• 如果沒有相符的主要和次要版本號碼的相符運行時間，則會使用下一個較高的次要版本。
• 預覽版本的執行階段或預覽版本與發行版本之間不會進行向前推進。 因此，使用預覽版本建立的 .NET 工具必須由作者重建並重新發佈並重新安裝。

在兩個常見案例中，預設不會發生向前移動：

• 只有較低版本的執行階段可用。 向前滾動只會選取較新版本的執行階段。
• 只有更高的主要執行環境版本可供使用。 向前移動不會跨越主要版本範圍。

如果應用程式找不到適當的運行時間，則無法執行並回報錯誤。

您可以使用下列其中一個命令，找出電腦上安裝的 .NET 執行時間：

dotnet --list-runtimes
dotnet --info

如果您認為此工具應該支援您目前已安裝的運行時間版本，您可以連絡工具作者，並查看它們是否可以更新版本號碼或多重目標。 一旦他們重新編譯並重新發佈其工具套件至 NuGet，並更新版本號碼，您就可以更新您這邊的版本。 雖然這不會發生，但您最快解決方案是安裝一個可以與您嘗試執行的工具相容的執行階段版本。 若要下載特定的 .NET 執行時間版本，請瀏覽 .NET 下載頁面。

如果您將 .NET SDK 安裝到非預設位置，您必須將環境變數設定為包含 dotnet 可執行文件的目錄 DOTNET_ROOT。

.NET 工具安裝失敗

安裝 .NET 全域或本機工具可能會失敗的原因有很多。 當工具安裝失敗時，您會看到類似下列訊息：

Tool '{0}' failed to install. This failure may have been caused by:

* You are attempting to install a preview release and did not use the --version option to specify the version.
* A package by this name was found, but it was not a .NET tool.
* The required NuGet feed cannot be accessed, perhaps because of an Internet connection problem.
* You mistyped the name of the tool.

For more reasons, including package naming enforcement, visit https://aka.ms/failure-installing-tool

為了協助診斷這些失敗，NuGet 訊息會直接顯示給用戶，以及之前的訊息。 NuGet 訊息可協助您找出問題。

• 套件命名強制執行
• 預覽版
• 套件不是 .NET 工具
• NuGet 摘要無法存取
• 套件標識碼不正確
• 401 （未經授權）

套件命名規範

Microsoft已變更其工具套件標識碼的指引，導致找不到具有預測名稱的一些工具。 新的指導方針是，所有Microsoft工具前面都會加上 「Microsoft」。此前置詞是保留的，只能用於以Microsoft授權憑證簽署的套件。

在轉換期間，某些Microsoft工具會有舊形式的套件標識碼，而其他工具則會有新的形式：

dotnet tool install -g Microsoft.<toolName>
dotnet tool install -g <toolName>

隨著套件識別碼的更新，您必須變更為新的套件識別碼，以取得最新的更新。 具有簡化工具名稱的套件將會淘汰。

預覽版本

• 您嘗試安裝預覽版本，但未使用 --version 選項來指定版本。

處於預覽狀態的 .NET 工具必須以名稱的一部分來指定，以指出它們處於預覽狀態。 您不需要包含整個預覽。 假設版本號碼採用預期格式，您可以使用類似下列範例的內容：

dotnet tool install -g --version 1.1.0-pre <toolName>

套件不是 .NET 工具

• 找到此名稱的 NuGet 套件，但不是 .NET 工具。

如果您嘗試安裝一般 NuGet 套件而非 .NET 工具的 NuGet 套件，您會看到類似下列的錯誤：

NU1212：<toolName>專案套件組合無效。 DotnetToolReference 項目樣式只能包含 DotnetTool 類型的參考。

無法存取 NuGet 摘要

• 無法存取必要的 NuGet 摘要，可能是因為因特網連線問題。

工具安裝需要存取包含工具套件的 NuGet 摘要。 如果供應不可用，它就會失敗。 您可以使用 nuget.config來改變摘要、要求特定 nuget.config 檔案，或使用 --add-source 參數指定其他摘要。 根據預設，NuGet 會對於無法連線的任何來源擲回錯誤。 旗標 --ignore-failed-sources 可以略過這些無法訪問的來源。

套件標識碼不正確

• 您輸入工具的名稱錯誤。

失敗的常見原因是工具名稱不正確。 這可能會因為混淆，或因為工具已移動或已被取代而發生。 為了確保您在 NuGet.org 上尋找工具時擁有正確的名稱，可以搜尋該工具，然後複製其安裝指令。

401 （未經授權）

您很可能已指定替代 NuGet 摘要，而且該摘要需要驗證。 有幾種不同的方式可以解決此問題：

• 新增 --ignore-failed-sources 參數，以略過私人信息流的錯誤，並使用公用 Microsoft 信息流。

  如果您要從 Microsoft NuGet 摘要安裝工具，則自定義摘要會在Microsoft的 NuGet 摘要傳回結果之前傳回此錯誤。 錯誤會終止請求，取消任何其他擱置的摘要請求，這可能是 Microsoft 的 NuGet 摘要。 新增 --ignore-failed-sources 選項會導致命令將此錯誤視為警告，並允許其他來源處理該要求。

  dotnet tool install -g --ignore-failed-sources <toolName>
  

• 使用 --add-source 參數強制 Microsoft NuGet 資料來源。

  全域或本機 NuGet 設定檔可能缺少 Microsoft NuGet 公共來源。 使用 --add-source 和 --ignore-failed-sources 參數的組合，以避免錯誤的饋送，並使用公用 Microsoft 饋送。

  dotnet tool install -g --add-source 'https://api.nuget.org/v3/index.json' --ignore-failed-sources <toolName>
  

• 使用自訂 NuGet 設定，--configfile <FILE> 參數。

  使用 Microsoft 公用 NuGet 源建立本機 nuget.config 檔案，並使用 --configfile 參數進行引用：

  dotnet tool install -g --configfile "./nuget.config" <toolName>
  

  以下是範例組態檔：

  <?xml version="1.0" encoding="utf-8"?>
  <configuration>
    <packageSources>
      <add key="nuget.org" value="https://api.nuget.org/v3/index.json" protocolVersion="3" />
    </packageSources>
  </configuration>
  

  如需詳細資訊，請參閱 nuget.config 參考。

• 將必要的認證新增至組態檔。

  如果您知道套件存在於已配置的來源中，請在 NuGet 組態檔中提供登入憑證。 如需 nuget 設定檔中認證的詳細資訊，請參閱 nuget.config 參考的 packageSourceCredentials 一節。

另請參閱

• .NET 工具