版本控制故障排除指南

项目
02/09/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
    }
  ]
}

由于 "default-features": false 设置，你预计 X 将在不包含其默认功能的情况下安装。但是，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 是一个直接依赖项，其中包含一个显式指令来排除默认功能。

有关默认功能工作原理以及如何对其进行管理的详细信息，请参阅默认功能概念文章一文。

此处未列出问题

如果此处未列出你的问题，请访问存储库创建新问题。

通过