版本控制疑難解答指南

發行項
02/06/2025

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

檢查網路連接埠的版本檔案

注意

以下所述的程式是針對來自 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 版本。
- 將 vcpkg.json 中的 version>= 約束更新為使用相容方案的版本。
覆寫至所需的版本：
- 如果您需要一個使用不同版本方案的特定 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 是直接相依性，其中包含排除預設功能的明確指示。

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

問題未列於此處

如果此處未列出您的問題，請瀏覽我們的存放庫以創建新的問題。

共用方式為