共用方式為

二進位快取疑難解答指南

  • 發行項

本指南適用於遇到二進位快取問題的使用者。

啟用 vcpkg 偵錯資訊

強烈建議您在遵循本指南時啟用偵錯輸出。

  • 傳統模式：新增 --debug 至命令調用。
  • CMake 工具鏈：在您的 CMake 設定呼叫或檔案CMakePresets.json中新增 -DVCPKG_INSTALL_OPTIONS="--debug" 。
  • MSBuild/Visual Studio：將 屬性 VcpkgAdditionalInstallOptions 設定為 --debug。
  • 將 VCPKG_INSTALL_OPTIONS 環境變數設定為 --debug。

NuGet 推送至 {url} 失敗

重要

將您的 vcpkg 工具更新為最新版本。 此外，針對完整的錯誤記錄啟用 偵錯輸出 。

使用 NuGet 二進位來源時，會出現下列錯誤：

Pushing NuGet to {url} failed. Use --debug for more information.

使用 NuGet 設定檔二進位來源時，會出現下列錯誤：

Pushing NuGet config to {url} failed. Use --debug for more information.

當 vcpkg 嘗試且無法使用 NuGet 命令行將套件上傳至 NuGet 摘要時，就會發生此錯誤。

原因 1：使用者寫入許可權不足

您遇到下列錯誤訊息：

System.Net.Http.HttpRequestException: Response status code does not indicate success: 403 (Forbidden - User <user> lacks permission to complete this action. You need to have 'AddPackage'.

遠端來源拒絕推送，因為用戶沒有足夠的寫入許可權。

原因 2：設定錯誤的 NuGet 摘要 URL

您可能會看到錯誤：

System.Net.Http.HttpRequestException: Response status code does not indicate success: 405 (Method Not Allowed).

伺服器拒絕 NuGet 的推送要求，因為它無法辨識要求方法。

  • 確認二進位來源中的 URI 正確無誤， <feed base url>/nuget/v3/index.json而且它通常會導向摘要的服務索引。

其他 NuGet 資源

如需在 NuGet 摘要上連線和發布指導方針，請參閱 NuGet 檔。

快取上傳錯誤

重要

將您的 vcpkg 工具更新為最新版本。 此外，針對完整的錯誤記錄啟用 偵錯輸出 。

您將二進位套件上傳至快取時發生錯誤。

原因 1：二進位快取提供者無法上傳

上傳可能會因為各種原因而失敗，而且錯誤訊息通常是提供者特定的。

空的二進位快取

重要

將您的 vcpkg 工具更新為最新版本。 此外，針對完整的錯誤記錄啟用 偵錯輸出 。

雖然您沒有遇到任何錯誤，但 vcpkg 安裝成功，但二進位快取會保持空白。 如果您觀察到錯誤，請參閱 NuGet 的推送疑難解答，並 上傳其他提供者的疑難解答。

原因 1：vcpkg 缺少二進位快取的寫入許可權

輸出中遺漏下列訊息。

Uploading binaries for 'rapidjson:x64-windows' to <binary source> source <url>.
Stored binaries in 1 destinations in 1.5 s.

vcpkg 略過將二進位套件上傳至二進位快取。

連結庫重建，而不是使用遠端二進位快取

重要

將您的 vcpkg 工具更新為最新版本。 此外，針對完整的錯誤記錄啟用 偵錯輸出 。

您的系統會在本機重建連結庫，即使遠端二進位快取中提供所需的二進位套件也一樣。

輸出中遺漏下列訊息。

Restored 1 package(s) from <remote binary cache> in 1.1 s. Use --debug to see more details.

原因 1：vcpkg 缺少遠端二進位快取的讀取許可權

vcpkg 選擇透過遠端讀取預設二進位快取。

原因 2：遠端二進位快取是空的

遠端快取應該包含您已推送的二進位套件清單。

原因 3：本機和遠端建置環境之間的差異

二進位快取中的每個套件都會加上 ABI 哈希 ，其中包含編譯程式版本、來源和其他資訊，以區分二進位套件。 如果本機計算的ABI 哈希不符合遠端儲存的哈希，則不會擷取封裝。

非預期或頻繁的連結庫重建

重要

將您的 vcpkg 工具更新為最新版本。 此外，針對完整的錯誤記錄啟用 偵錯輸出 。

在未變更的環境中，且未更新 vcpkg，您仍然發現自己自行重建連結庫。

原因 1：建置環境中未偵測到的變更

二進位快取中的每個套件都會加上 ABI 哈希 ，其中包含編譯程式版本、來源和其他資訊，以區分二進位套件。 如果本機計算的ABI 哈希不符合遠端儲存的哈希，則不會擷取封裝。

針對 ABI 哈希不符進行疑難解答

重要

將您的 vcpkg 工具更新為最新版本。 此外，針對完整的錯誤記錄啟用 偵錯輸出 。

本指南適用於用戶診斷為何針對兩個同名二進位套件有不同的 ABI 哈希。

比較兩個二進位套件

判斷兩個同名套件之間的差異需要比較各種數據：來源、工具版本、編譯程式和目標平臺。 ABI 哈希提供此數據的簡潔表示法。 計算 ABI 哈希時，vcpkg 會考慮所有相關數據，包括檔案內容、工具版本和系統詳細數據。 它會為每個數據點建立哈希，然後將這些哈希合併為二進位封裝的單一值。

二進位套件 ABI 哈希比較

連結 庫 zlib 的 ABI 哈希 為 bb1c96759ac96102b4b18215db138daedd3eb16c2cd3302ae7bffab2b643eb87：

[DEBUG] Trying to hash <path>\buildtrees\zlib\x86-windows.vcpkg_abi_info.txt
[DEBUG] <path>\buildtrees\zlib\x86-windows.vcpkg_abi_info.txt has hash bb1c96759ac96102b4b18215db138daedd3eb16c2cd3302ae7bffab2b643eb87

如果相同連結庫執行之間的哈希變更，這表示這兩個套件是相異的。

編譯程式版本 ABI 哈希比較

確認您的編譯程式版本是否在執行之間變更。

[DEBUG] -- The C compiler identification is MSVC 19.36.32538.0
[DEBUG] -- The CXX compiler identification is MSVC 19.36.32538.0
[DEBUG] #COMPILER_HASH#f5d02a6542664cfbd4a38db478133cbb1a18f315

編譯程式哈希為 f5d02a6542664cfbd4a38db478133cbb1a18f315。

ABI 哈希項目比較

比較每個套件的 ABI 專案。 專案代表參與最終哈希的資訊片段。

[DEBUG] <abientries for zlib:x86-windows>
[DEBUG]   0001-Prevent-invalid-inclusions-when-HAVE_-is-set-to-0.patch|750b9542cb55e6328cca01d3ca997f1373b9530afa95e04213168676936e7bfa
[DEBUG]   0002-skip-building-examples.patch|835ddecfed752e0f49be9b0f8ff7ba76541cb0a150044327316e22ca84f8d0c2
[DEBUG]   0003-build-static-or-shared-not-both.patch|d6026271dcb3d8fc74b41e235620ae31576a798e77aa411c3af8cd9e948c02b1
[DEBUG]   0004-android-and-mingw-fixes.patch|37a43eddbcb1b7dde49e7659ae895dfd0ff1df66666c1371ba7d5bfc49d8b438
[DEBUG]   cmake|3.26.2
[DEBUG]   features|core
[DEBUG]   portfile.cmake|ac63047b644fa758860dd7ba48ff9a13b058c6f240b8e8d675b8fbba035976be
[DEBUG]   ports.cmake|5a8e00cedff0c898b1f90f7d129329d0288801bc9056562b039698caf31ff3f3
[DEBUG]   post_build_checks|2
[DEBUG]   powershell|7.3.6
[DEBUG]   triplet|x86-windows
[DEBUG]   triplet_abi|3e71dd1d4afa622894ae367adbbb1ecbd42c57c51428a86b675fa1c8cad3a581-36b818778ba6f2c16962495caedb9a7b221d5be4c60de1cd3060f549319a9931-f5d02a6542664cfbd4a38db478133cbb1a18f315
[DEBUG]   usage|be22662327df993eebc437495add75acb365ab18d37c7e5de735d4ea4f5d3083
[DEBUG]   vcpkg-cmake|1b3dac4b9b0bcbef227c954b495174863feebe3900b2a6bdef0cd1cf04ca1213
[DEBUG]   vcpkg-cmake-wrapper.cmake|5d49ef2ee6448479c2aad0e5f732e2676eaba0411860f9bebabe6002d66f57d1
[DEBUG]   vcpkg.json|bc94e2540efabe36130a806381a001c57194e7de67454ab7ff1e30aa15e6ce23
[DEBUG]   vcpkg_copy_pdbs|d57e4f196c82dc562a9968c6155073094513c31e2de475694143d3aa47954b1c
[DEBUG]   vcpkg_fixup_pkgconfig|588d833ff057d3ca99c14616c7ecfb5948b5e2a9e4fc02517dceb8b803473457
[DEBUG]   vcpkg_from_git|8f27bff0d01c6d15a3e691758df52bfbb0b1b929da45c4ebba02ef76b54b1881
[DEBUG]   vcpkg_from_github|b743742296a114ea1b18ae99672e02f142c4eb2bef7f57d36c038bedbfb0502f
[DEBUG]   vcpkg_replace_string|d43c8699ce27e25d47367c970d1c546f6bc36b6df8fb0be0c3986eb5830bd4f1
[DEBUG] </abientries>

注意

專案 triplet_abi 包含三個哈希：三元組檔案內容的 x86-windows 哈希、 windows.cmake 工具鏈和編譯程式哈希。 如果您決定以不同的平臺為目標，這些哈希將會變更。

不符 1：埠檔案

埠檔案包括埠腳本 （portfile.cmake、 vcpkg.json、修補程式檔案或*.patch埠目錄中的任何其他檔案： ports/<library>/*。

原因 1：CI 或管線已更新埠登錄

在 vcpkg 在您的 CI 中執行之前，它會複製最新的 vcpkg 存放庫。

  • 使用 git clone https://github.com/microsoft/vcpkg 後面接著 bootstrap 文本時，請確定您簽出至特定的認可。
  • 請考慮將 vcpkg 新增為 git 子模組至您的專案。

原因 2：GitHub Actions 已更新 vcpkg

您使用的是 GitHub Actions 所提供的 vcpkg 系統複本，此複本已更新。

  • 複製您自己的 vcpkg 複本。
  • 請考慮在專案中將 vcpkg 設定為 git 子模組。

不符 2：vcpkg CMake 協助程式函式

CMake 協助程式函式位於腳本目錄中： scripts/*，通常以 vcpkg_開頭。

原因 1：CI 或管線更新的協助程式腳本

在 vcpkg 在您的 CI 中執行之前，它會複製最新的 vcpkg 存放庫。

  • 使用 git clone https://github.com/microsoft/vcpkg 後面接著 bootstrap 文本時，請確定您簽出至特定的認可。
  • 請考慮將 vcpkg 新增為 git 子模組至您的專案。

原因 2：GitHub Actions 已更新 vcpkg

您使用的是 GitHub Actions 所提供的 vcpkg 系統複本，此複本已更新。

  • 複製您自己的 vcpkg 複本。
  • 請考慮在專案中將 vcpkg 設定為 git 子模組。

不符 3：編譯程式版本

vcpkg 會以不同版本的編譯程式重建相依性。

原因 1：Visual Studio C++編譯程序自動更新。

Visual Studio 會在執行之間自動更新C++工作負載，包括編譯程式。 即使是次要版本更新，也會造成 vcpkg 重建連結庫集合。

原因 2：連結庫建置在與用來取用它的電腦不同的電腦上。

一部機器已建立二進位套件並發行至遠端快取。 另一部通常用於開發的計算機已取用快取的連結庫。

  • 在本機使用與遠端電腦上相同的C++編譯程式版本。 針對 Visual Studio，請考慮固定 版本啟動載入器。
  • 在本機重建相依性以供開發之用。 稍後在持續整合期間測試並解決問題。

原因 3：自我裝載映射已更新編譯程式。

您用來建置 vcpkg 相依性的基礎映像已變更，這會更新編譯程式版本。

  • 釘選到穩定且已建立版本的映像。 請確定您未擷取最新的映像，因此不會在執行之間自動更新基礎工具或編譯程式。
  • 如果您需要經常更新映像，請在建立映像時，將C++編譯程式工具釘選到特定版本。

原因 4：GitHub 託管的執行器已更新基礎編譯程式。

裝載的 GitHub 執行器會每周更新編譯程式和工具。

不符 4：執行之間的工具版本已變更。

用來建置連結庫的工具版本 CMake 或 PowerShell 在執行之間已變更。

原因 1：Visual Studio 自動更新。

Visual Studio 會在執行之間自動更新，包括任何工具。 即使是次要版本更新，也會造成 vcpkg 重建連結庫集合。

  • 停用自動 Visual Studio 更新。
  • 將 新增 --x-abi-tools-use-exact-versions 至您的 vcpkg 調用。 這會根據 中的 vcpkgTools.xml版本修正工具的 ABI;如果必要，vcpkg 會擷取自己的複本。

原因 2：連結庫建置在與用來取用它的電腦不同的電腦上。

一部機器已建立二進位套件並發行至遠端快取。 另一部通常用於開發的計算機已取用快取的連結庫。

  • 在本機使用與遠端電腦上相同的工具版本。
  • 在本機重建相依性以供開發之用。 稍後在持續整合期間測試並解決問題。
  • 將 新增 --x-abi-tools-use-exact-versions 至您的 vcpkg 調用。 這會根據 中的 vcpkgTools.xml版本修正工具的 ABI;如果必要，vcpkg 會擷取自己的複本。

原因 3：自我裝載映射已更新工具。

您用來建置 vcpkg 相依性的基礎映像已變更，這是使用的任何工具版本。

  • 釘選到穩定且已建立版本的映像。 請確定您未擷取最新的映像，因此不會在執行之間自動更新基礎工具。
  • 如果您需要經常更新映像，請在建立映像時，將任何相關的工具釘選到特定版本。
  • 將 新增 --x-abi-tools-use-exact-versions 至您的 vcpkg 調用。 這會根據 中的 vcpkgTools.xml版本修正工具的 ABI;如果必要，vcpkg 會擷取自己的複本。

原因 4：GitHub 託管的執行器已更新基礎工具。

裝載的 GitHub 執行器會每周更新編譯程式和工具。

  • 將 新增 --x-abi-tools-use-exact-versions 至您的 vcpkg 調用。 這會根據 中的 vcpkgTools.xml版本修正工具的 ABI;如果必要，vcpkg 會擷取自己的複本。

其他選項

如果上述選項無法運作，請考慮下列因應措施：

  • 使用 vcpkg export 來產生相依性的獨立封存，而不是從指令清單還原它們。
  • 請考慮使用 Docker 自我裝載映像來建置連結庫
  • 執行輔助持續整合，以一般頻率建置 vcpkg 連結庫（例如每日或每周）

問題並未在此列出

如果此處未列出您的問題，請造訪 我們的存放庫 以建立新的問題。