Windows Package Manager (winget) 清单文件编写指南

Windows Package Manager (winget) 清单文件编写指南

winget-pkgs The Microsoft community Windows Package Manager manifest repository 项目地址: https://gitcode.com/gh_mirrors/wi/winget-pkgs

什么是Windows Package Manager清单

Windows Package Manager（简称winget）是微软开发的Windows软件包管理工具，它通过YAML格式的清单文件（manifest）来描述软件包的元数据和安装信息。这些清单文件包含了软件包的标识符、版本、安装程序位置等重要信息，使得用户可以通过简单的命令行操作来安装、升级和管理软件。

核心概念解析

清单文件结构

每个软件包的清单由三个必需文件组成：

1. 版本文件：定义软件包的基本版本信息
2. 默认区域设置文件：包含软件包的名称、描述等本地化信息
3. 安装程序文件：指定下载位置和安装参数

软件包标识规则

每个软件包都有唯一的标识符（PackageIdentifier），通常采用"发布者.软件名"的格式，例如：

• Microsoft.WindowsTerminal
• Google.Chrome

版本规范

软件版本（PackageVersion）可以采用多种格式：

• 语义化版本（SemVer）：如1.0.0
• 日期版本：如2023.08.15
• 自定义版本：如v2.1-release

清单文件目录结构

清单文件在仓库中的存储路径遵循特定规则：

manifests/首字母小写/发布者/软件名/版本号/

例如，Microsoft Windows Terminal 1.6.10571.0的路径为： manifests/m/Microsoft/WindowsTerminal/1.6.10571.0

创建清单前的准备工作

在创建新清单前，务必确认：

1. 该软件包是否已存在（使用winget search命令查询）
2. 检查是否有其他人已经提交了相同软件的清单
3. 确保你有该软件的合法分发权限

清单创建工具推荐

Winget-Create工具

微软官方提供的命令行工具，可引导用户完成清单创建过程：

winget install wingetcreate
wingetcreate new <安装程序URL>

该工具会自动：

• 提取软件包基本信息
• 生成合规的YAML结构
• 进行基本验证

手动创建注意事项

如需手动编辑YAML文件，需注意：

1. 严格遵循缩进规则（YAML对缩进敏感）
2. 使用UTF-8编码
3. 字段名称区分大小写
4. 完成后使用winget validate命令验证

高级配置技巧

安装程序架构处理

需特别注意安装程序的架构标识：

• 应反映实际安装的二进制文件架构，而非安装程序本身
• 例如：32位安装程序安装64位软件时，应标记为x64

AppsAndFeaturesEntries配置

当安装程序写入注册表的信息不规范时，需要额外配置：

1. 版本匹配问题：当DisplayName或ProductCode包含版本信息时
2. 版本差异：PackageVersion与安装程序的DisplayVersion不一致时
3. 特殊版本格式：使用日期、哈希等非常规版本时
4. 安装类型不匹配：如EXE安装程序内嵌MSI时

配置示例：

AppsAndFeaturesEntries:
  - DisplayName: Example
    DisplayVersion: 1.0.0
    Publisher: Example Inc
    ProductCode: "{XXXXX-XXXX-XXXX-XXXX-XXXXXX}"
    InstallerType: msi

版本排序规则详解

winget采用智能版本比较算法：

1. 预处理：去除版本字符串开头的非数字字符
2. 分段处理：按点号(.)分割版本字符串
3. 部分比较：每段分为整数部分和字符串部分分别比较
4. 特殊规则：
   • 无后缀的版本 > 有后缀的版本（如1.0 > 1.0-beta）
   • 数字部分优先于字符串部分比较

示例比较：

• 1.2.0 == 1.2（自动补零）
• 1.2 > 1.2-rc（无后缀优先）
• v1.2 > 1.1（去除前缀后比较）

测试与验证

提交清单前必须进行充分测试：

1. 基本测试：

   winget settings --enable LocalManifestFiles
   winget install --manifest <路径>
   

2. 沙盒测试：推荐使用Windows沙盒环境测试

3. 验证要点：

   • 确认软件能静默安装
   • 验证安装后的版本匹配
   • 检查发布者和名称是否正确

最佳实践建议

1. 版本规范：尽量使用语义化版本
2. 架构标识：准确反映实际安装的二进制架构
3. 多文件清单：优先采用多文件格式而非单文件
4. 全面测试：在不同环境验证安装行为
5. 持续更新：及时跟进软件的新版本发布

通过遵循这些指南，你可以为Windows Package Manager生态系统贡献高质量的软件包清单，帮助更多用户便捷地获取和管理Windows软件。

winget-pkgs The Microsoft community Windows Package Manager manifest repository 项目地址: https://gitcode.com/gh_mirrors/wi/winget-pkgs