對套件還原錯誤進行疑難排解

  • 發行項

本文著重於還原套件時常見的錯誤及其解決步驟。

套件還原會嘗試將所有套件相依性安裝到符合專案檔 (.csproj) 或您的 packages.config 檔案中套件參考的正確狀態。 (在 Visual Studio 中，參考會出現 方案總管在 [相依性 \ NuGet] 或 [參考] 節點底下的 [參考] 節點底下。) 若要遵循還原套件的必要步驟，請參閱還原套件。 如果專案檔 (.csproj) 或您的 packages.config 檔案中的套件參考不正確 (不符合您在套件還原之後所需的狀態)，則您需要安裝套件或更新套件，而不是使用套件還原。

如果此處的指示不適用於您的情況，請在 GitHub 上提出發生的問題，讓我們能更仔細審視您的案例。 請勿使用會出現在此頁面上的「此頁面有説明嗎？」控制項，因為它無法讓我們連絡您以取得詳細資訊。

適用於 Visual Studio 使用者的快速解決方案

如果您使用 Visual Studio，請先以下列方式啟用套件還原。 否則，請繼續瀏覽後續各節。

  1. 選取[工具 > ] > NuGet 封裝管理員 封裝管理員 設定功能表命令。
  2. 設定 [套件還原] 下的兩個選項。
  3. 選取 [確定] 。
  4. 再次建置您的專案。

Enable NuGet package restore in Tool/Options

這些設定也可以在您的 NuGet.Config 檔案中變更；請參閱同意一節。 如果您的專案是使用整合 MSBuild 套件還原的舊版專案，您可能需要遷移至自動套件還原。

此專案參考的 NuGet 套件不在這部電腦上

完整的錯誤訊息：

This project references NuGet package(s) that are missing on this computer.
Use NuGet Package Restore to download them. The missing file is {name}.

當您嘗試建置包含一或多個 NuGet 套件參考的專案，但這些套件目前並未安裝在電腦上或位於專案中時，就會發生這項錯誤。

  • 使用 PackageReference 管理格式時，此錯誤可能是從packages.config移轉至 PackageReference 移轉，而且必須手動從專案檔 中移除 。
  • 當使用 packages.config 時，此錯誤表示套件並未安裝在解決方案根目錄的 packages 資料夾中。

當您從原始檔控制或另一個下載處取得專案的原始程式碼時，通常就會發生這種情況。 套件通常會從原始檔控制或下載中省略，因為可以從類似 nuget.org 的套件摘要中還原 (請參閱套件和原始檔控制)。 包含套件反而會使存放庫膨脹，或建立不必要的大型 .zip 檔案。

如果您的專案檔包含套件位置的絕對路徑，而您又移動了專案，也會發生錯誤。

請使用下列其中一種方法來還原套件：

成功還原之後，套件應該存在於 global-packages 資料夾中。 對於使用 PackageReference 的專案，還原應重新建立 obj/project.assets.json 檔案；針對使用 packages.config 的專案，套件應該會出現在專案的 packages 資料夾中。 專案現在應可順利建置。 如果沒有，請在 GitHub 上提出發生的問題以便我們與您連絡。

找不到資產檔案 project.assets.json

完整的錯誤訊息：

Assets file '<path>\project.assets.json' not found. Run a NuGet package restore to generate this file.

當使用 PackageReference 管理格式時，project.assets.json 檔案會維護專案的相依性關係圖，此圖是用來確認電腦上已安裝所有必要套件的。 因為此檔案是透過套件還原動態產生的，因此通常不會新增到原始檔控制。 因此當使用不會自動還原套件的 msbuild 之類的工具建立專案時，會發生此錯誤。

在此情況下，請在執行 msbuild -t:restore 後接著執行 msbuild，或使用 dotnet build (會自動還原套件)。 您也可以使用上一節中的任何一個套件還原方法。

完整的錯誤訊息：

One or more NuGet packages need to be restored but couldn't be because consent has
not been granted. To give consent, open the Visual Studio Options dialog, click on
the NuGet Package Manager node and check 'Allow NuGet to download missing packages
during build.' You can also give consent by setting the environment variable
'EnableNuGetPackageRestore' to 'true'. Missing packages: {name}

此錯誤指出您的 NuGet 組態已停用套件還原。

您可以在 Visual Studio 中變更適用的設定，如先前在適用於 Visual Studio 使用者的快速解決方案所述。

您也可以直接在適用的 nuget.config 檔案上編輯這些設定 (在 Windows 上通常為 %AppData%\NuGet\NuGet.Config，在 Mac/Linux 上則為 ~/.nuget/NuGet/NuGet.Config)。 請確認 packageRestore 底下的 enabled 和 automatic 金鑰設定為 True：

<!-- Package restore is enabled -->
<configuration>
    <packageRestore>
        <add key="enabled" value="True" />
        <add key="automatic" value="True" />
    </packageRestore>
</configuration>

重要

如果您直接在 nuget.config 中編輯 packageRestore 設定，請重新啟動 Visual Studio，讓選項對話方塊顯示目前的值。

其他可能的情況

  • 您可能會因為遺失檔案而遇到建置錯誤，會有訊息指出應使用 NuGet 還原加以下載。 不過，執行還原可能會說：「所有套件都已安裝，而且沒有可還原的專案」。在此情況下，在使用 packages.config PackageReference) 時，使用) 或 obj/project.assets.json 檔案 (時，刪除 packages 資料夾 (，然後再次執行還原。 如果錯誤持續發生，請從命令列使用 nuget locals all -clear 或 dotnet nuget locals all --clear 以清除 global-packages 和快取資料夾，如管理全域套件和快取資料夾中所述。

  • 從原始檔控制取得專案時，您的專案資料夾可能會設定成唯讀。 請變更資料夾的權限，然後再次嘗試還原套件。

  • 您使用的可能是舊版 NuGet。 請查看 nuget.org/downloads 以取得最新的建議版本。 若是 Visual Studio 2015，建議使用 3.6.0。

如果您遇到其他問題，請在 GitHub 上提出發生的問題以便我們向您取得更多詳細資料。