版本控制疑難解答指南

發行項
04/04/2024

本指南適用於遇到版本設定問題的使用者。

檢查埠的版本檔案

注意

以下所述的程式是針對來自 vcpkg 登錄的埠運作。請參閱我們的登錄檔，以瞭解版本設定資料庫如何在自定義登錄中實作。

若要檢查特定埠的版本資料庫：

瀏覽至 vcpkg/versions 目錄。
找出埠的資料夾：
- 尋找對應至埠第一個字母的資料夾。例如，針對 fmt 開啟名為 f-的資料夾。
開啟埠版本檔案：
- 找出具有相同埠名稱的 JSON 檔案。例如，版本 fmt 檔案的名稱為 fmt.json.

埠的版本檔案包含可用版本清單，其中包含版本標籤及其對應的 Git 樹狀結構物件哈希等詳細數據。 vcpkg 需要此資訊才能擷取特定的埠版本。只有此清單中所包含的版本可用於您的指令清單檔案。

如需版本設定的詳細資訊，請參閱我們的參考檔：

如需使用指令清單的詳細資訊，請參閱指令清單

原因：要求套件不存在的版本

當指令清單檔中指定的版本不存在於 vcpkg 版本資料庫中時，vcpkg 無法解析相依性，併產生如下的錯誤訊息：

error: no version database entry for fmt at 100.0.0
Available versions:
  10.1.1
  10.1.0
  10.0.0
  9.1.0#1
  9.1.0
  9.0.0
  8.1.1#2
  8.1.1#1
  ...
See `vcpkg help versioning` or https://learn.microsoft.com/vcpkg/users/versioning for more information.

若要解決問題：

更新版本資料庫：
- 您想要的版本可能不在版本的本機複本中。在此情況下，請執行 git pull 命令，將 vcpkg 登錄更新為最新的認可。
檢查可用的版本：
- 選擇版本資料庫中可用的其中一個版本。
更新指令清單檔案：
- 編輯您的 vcpkg.json 檔案。
- 將指定的版本變更為 vcpkg 存放庫中可用的版本。例如，從 “version>=”： “100.0.0” 變更為 “version>=”： “10.1.1”。
執行 vcpkg install：
- vcpkg install在您的終端機或命令提示字元中再次執行命令。

原因：跨不同配置指定版本條件約束

當相依性檔案中指定的 vcpkg.json 版本使用不同於 vcpkg 存放庫基準版本中使用的版本設定配置時，就會發生版本配置衝突。這會導致發生錯誤，因為 vcpkg 無法比較不同配置之間的版本。

如果宣告 version>= 的條件約束使用的版本配置與基準版本中使用的版本配置不同，vcpkg 無法判斷哪個版本大於或等於另一個版本。

例如，如果您指定：

{
  "dependencies": [
    {
      "name": "boost-regex",
      "version>=": "1.75.0"
    }
  ]
}

vcpkg 會輸出下列錯誤訊息：

error: version conflict on boost-regex:x64-windows:  required 1.75.0, which cannot be compared with the baseline version 1.83.0.

The versions have incomparable schemes:
  boost-regex@1.83.0 has scheme relaxed
  boost-regex@1.75.0 has scheme string

This can be resolved by adding an explicit override to the preferred version. For example:

  "overrides": [
    { "name": "boost-regex", "version": "1.83.0" }
  ]

See `vcpkg help versioning` or https://learn.microsoft.com/vcpkg/users/versioning for more information.

解決方式：

使用相容的版本設定：
- 檢查下 vcpkg 存放庫中 versions/b-/boost-regex.json 的版本資料庫，以尋找使用與基準相同版本設定配置的版本 boost-regex 。
- 將 version>= 中的 vcpkg.json 條件約束更新為使用相容配置的版本。
覆寫至所需的版本：
- 如果您需要使用不同版本設定配置的特定 boost-regex 版本，您可以在指令清單中覆寫它。
- 修改以 vcpkg.json 包含指定所需版本的覆寫區段：
```
{
  "dependencies": [
    { "name": "boost-regex" }
  ],
  "overrides": [
    { "name": "boost-regex", "version": "1.75.0" }
  ]
}
```

原因：淺層複製中的認可歷程記錄不足

使用有限的認可歷程記錄複製 vcpkg 時，它缺少解決特定版本限制或基準的必要認可歷程記錄。 vcpkg 用來擷取特定埠版本的 Git 樹狀目錄物件哈希，只有在取出完整認可歷程記錄時才能使用。vcpkg 會偵測它何時已複製到淺層存放庫，並在無法擷取埠版本時產生錯誤訊息。

例如，搭配特定基準使用 vcpkg.json ，如下所示：

{
  "dependencies": [
    {
      "name": "fmt"
    }
  ],
  "overrides": [
    {
      "name": "fmt",
      "version": "7.1.3#1"
    }
  ],
  "builtin-baseline": "bb588985e37484d543fc849d0d79434e0d45bb3c"
}

將會產生下列錯誤：

error: failed to execute: "C:\Program Files\Git\cmd\git.exe" "--git-dir=C:\dev\demo\vcpkg\.git" "--work-tree=C:\dev\demo\vcpkg\buildtrees\versioning_\versions\fmt\4f8427eb0bd40da1856d4e67bde39a4fda689d72_26648.tmp" -c core.autocrlf=false read-tree -m -u 4f8427eb0bd40da1856d4e67bde39a4fda689d72
vcpkg was cloned as a shallow repository in: C:\dev\demo\vcpkg\.git
Try again with a full vcpkg clone.
error: git failed with exit code: (128).
fatal: failed to unpack tree object 4f8427eb0bd40da1856d4e67bde39a4fda689d72
note: while checking out port fmt with git tree 4f8427eb0bd40da1856d4e67bde39a4fda689d72

此錯誤表示淺層複製中無法使用特定套件版本fmt所需的認可（4f8427eb0bd40da1856d4e67bde39a4fda689d72）。

解決方式：

轉換為完整複製
- 此問題最簡單的解決方案是轉換成完整複製：
```
git fetch --unshallow
```
使用 GitHub Actions （預設淺層複製品）
- GitHub Actions 通常會預設為淺層複製。若要解決此問題，您可以修改 GitHub Actions 工作流程以執行完整複製。使用 vcpkg 之前，請先新增下列步驟：
```
- name: Convert to Full Clone
  run: git fetch --unshallow
```

原因：在可轉移相依性中未預期的包含預設功能

使用 vcpkg 管理相依性時，您可能會發現可轉移的相依性會隨其預設功能一起安裝，即使您可能不想要項目的這些功能也一併安裝。這種情況可能會導致最終組建中的非預期膨脹或功能。

案例

您相依於連結庫，而連結庫 Y則依存於連結庫 X。連結庫 X 有預設功能，包括 foo您要從專案排除的。連結庫 Y 的最上層指令清單看起來可能如下所示：

{
  "name": "my-project",
  "dependencies": [
    {
      "name": "Y",
      "features": ["featureB"],
      "default-features": false
    }
  ]
}

您預期 X 會因為設定而未安裝預設功能 "default-features": false 。不過， X 仍會隨預設功能 foo一起安裝。

原因

屬性 default-features 只會在最上層指令清單中考慮。這表示除非在最上層明確停用，否則仍會包含可轉移相依性的預設功能（例如 X 在此案例中）。解析連結庫 Y 時， vcpkg 不會將 "default-features": false 設定傳播至可轉移的相 X依性，導致安裝 X 具有其預設功能的。

解決方法

若要確保這類 X 的可轉移相依性在沒有其預設功能的情況下安裝，您必須將其升階為最上層指令清單中的直接相依性，並明確停用其預設功能。變更以 vcpkg.json 直接包含 X "default-features": false：

{
  "name": "my-project",
  "dependencies": [
    {
      "name": "Y",
      "features": ["featureB"]
    },
    {
      "name": "X",
      "default-features": false
    }
  ]
}

此方法可確保 X 未安裝其預設功能，因為現在是 X 直接相依性，並明確指示排除預設功能。

如需預設功能運作方式及管理方式的詳細資訊，請參閱預設功能概念文章。

問題並未在此列出

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

共用方式為