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

全域工具

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

OS	路徑
Linux/macOS	$HOME/.dotnet/tools
Windows	%USERPROFILE%\.dotnet\tools

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

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

• 如果您使用 Linux，且使用 .tar.gz 檔案而非 apt-get 或 rpm 安裝 .NET SDK。
• 使用 macOS 10.15「Catalina」或更新版本。
• 如果您使用 macOS 10.14 "Mojave" 或更早版本，且使用 .tar.gz 檔案而非 .pkg 安裝 .NET SDK。
• 如果您已安裝 .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_ROOT 設定為包含 dotnet 可執行檔的目錄。

.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 的工具，您可以直接在 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 工具