本文旨在帮助 uts 插件开发者和使用者，快速了解 uts 插件中配置使用 Swift Package Manager 依赖的问题。

此功能 HBuilder X 4.8.3+ 版本支持

在 uts 插件中使用 Swift Package Manager 依赖

在 uts 插件中使用 Swift Package Manager 依赖库，需要在 config.json 中 dependencies-spms 节点做相应配置，下面是配置示例：

{
	"deploymentTarget": "12.0",   // 可选，插件支持的最低 iOS 版本  默认：12.0
	"dependencies-spms": [ // 可选, 需要依赖的 Swift Package Manager 库, HBuilderX 4.8.3+ 版本支持
	// 1. exactVersion - 精确版本匹配：
	{
		"name": "Alamofire",
		"url": "https://github.com/Alamofire/Alamofire.git",
		"kind": "exactVersion",
		"version": "5.7.1"
	},

	// 2. upToNextMajorVersion - 默认最常用：
	{
		"name": "Alamofire", 
		"url": "https://github.com/Alamofire/Alamofire.git",
		"kind": "upToNextMajorVersion",
		"minimumVersion": "5.7.1"
	},

	// 3. upToNextMinorVersion - 小版本兼容：
	{
		"name": "Alamofire",
		"url": "https://github.com/Alamofire/Alamofire.git", 
		"kind": "upToNextMinorVersion",
		"minimumVersion": "5.7.1"
	},

	// 4. versionRange - 版本区间：
	{
		"name": "Alamofire",
		"url": "https://github.com/Alamofire/Alamofire.git",
		"kind": "versionRange", 
		"minimumVersion": "5.7.1",
		"maximumVersion": "5.7.8"
	},

	// 5. branch - 分支跟踪：
	{
		"name": "Alamofire",
		"url": "https://github.com/Alamofire/Alamofire.git",
		"kind": "branch",
		"branch": "main"
	},

	// 6. revision - 提交锁定：
	{
		"name": "Alamofire",
		"url": "https://github.com/Alamofire/Alamofire.git", 
		"kind": "revision",
		"revision": "2053b120767c42a70bcba21095f34e4cfb54a75d"
	}]
}

注意：

1. 拷贝以上代码时请手动删除注释，实际项目中 config.json 中不能包含注释信息；
2. GitHub、GitLab、Bitbucket 等国外代码托管服务访问速度慢或被限制，下载 Swift Package Manager 依赖库时需使用VPN；
3. 上述config配置中完整列举了6种不同的Swift Package Manager 依赖下载方式；
4. Xcode默认已经支持Swift Package Manager环境，不需要类似CocoaPods单独配置所需环境；

配置说明：

基本配置参数

参数	类型	必需	说明
deploymentTarget	String	否	插件支持的最低 iOS 版本号，默认设置为 12.0。需要满足所有依赖库（CocoaPods + SPM）的最低版本要求
dependencies-spms	Array	否	需要依赖的 Swift Package Manager 库，HBuilderX 4.8.3+ 版本支持

注意：

• CocoaPods 依赖：插件支持的最低版本号应该设置为所有依赖的三方库（包含 framework .a pod ）中最低支持版本号中的最高的一个
• SPM 依赖：SPM 依赖库的最低 iOS 版本要求定义在各自的 Package.swift 文件的 platforms 字段中，需要读取并计算所有 SPM 依赖的最低版本要求
• 最终计算：deploymentTarget 应该设置为所有依赖库（CocoaPods + SPM）中最低支持版本号中的最高值

dependencies-spms 配置参数

参数	类型	必需	说明
name	String	是	SPM 库的产品名称，对应 Package.swift 中 products 数组里的 library name，不可为 nil， 注意包名和产品名不一定相同
url	String	是	SPM 库的 Git 仓库地址，不可为 nil
kind	String	是	依赖类型，不可为 nil, 有效值：exactVersion、upToNextMajorVersion、upToNextMinorVersion、versionRange、branch、revision

⚠️ 重要提醒：name 字段配置错误会导致 UTS 插件编译失败！必须使用 Package.swift 中 products 数组里定义的 library name，而不是包名。

name 字段详细说明

name 字段需要配置为 Swift Package 中定义的产品名称，请查看三方库git地址根目录中Package.swift文件（如果三方库支持spm），具体对应关系如下：

1. Package.swift 中的定义

// Package.swift
let package = Package(
    name: "SwiftProtobuf",  // 这是包名，不是我们要的
    products: [
        .library(
            name: "SwiftProtobuf",  // 这是产品名，对应 config.json 中的 name
            targets: ["SwiftProtobuf"]
        ),
    ],
    // ... 其他配置
)

2. config.json 中的配置

{
    "name": "SwiftProtobuf",  // 对应上面的 .library(name: "Protobuf")
    "url": "https://github.com/apple/swift-protobuf.git",
    "kind": "upToNextMajorVersion",
    "minimumVersion": "1.20.0"
}

kind 类型详细说明

kind 类型	必需参数	说明	版本范围示例
exactVersion	version	精确版本匹配	固定版本 5.7.1
upToNextMajorVersion	minimumVersion	默认最常用，主版本兼容	[5.7.1, 6.x) 左闭右开
upToNextMinorVersion	minimumVersion	小版本兼容	[5.7.1, 5.8.x) 左闭右开
versionRange	minimumVersion, maximumVersion	版本区间设置	[5.7.1, 5.7.8) 左闭右开
branch	branch	分支跟踪	跟踪指定分支（如 main）
revision	revision	提交锁定	锁定具体 commit hash

版本范围说明

• upToNextMajorVersion: 自动升级兼容未来主版本，如 "5.7.1" 会升级到 5.x 版本，但不会升级到 6.x
• upToNextMinorVersion: 自动升级兼容未来小版本，如 "5.7.1" 会升级到 5.7.x 版本，但不会升级到 5.8.x
• versionRange: 在指定版本区间内自动升级，如 [5.7.1, 5.7.8) 表示从 5.7.1 到 5.7.8（不包含）

实际项目示例

示例 1：Alamofire

Package.swift 中的定义：

// https://github.com/Alamofire/Alamofire/blob/master/Package.swift
let package = Package(
    name: "Alamofire",  // 包名
    products: [
        .library(
            name: "Alamofire",  // 产品名，与包名相同
            targets: ["Alamofire"]
        ),
    ],
    // ... 其他配置
)

config.json 中的正确配置：

{
    "name": "Alamofire",  // 正确：使用 products 中的 name
    "url": "https://github.com/Alamofire/Alamofire.git",
    "kind": "upToNextMajorVersion",
    "minimumVersion": "5.7.1"
}

示例 2：Swift Collections

Package.swift 中的定义：

// https://github.com/apple/swift-collections/blob/main/Package.swift
let package = Package(
    name: "swift-collections",  // 包名
    products: [
        .library(
            name: "Collections",  // 产品名，与包名不同
            targets: ["Collections"]
        ),
        .library(
            name: "DequeModule",  // 另一个产品名
            targets: ["DequeModule"]
        ),
    ],
    // ... 其他配置
)

常见错误示例

❌ 错误配置：

{
    "name": "swift-collections",  // 错误：这是包名，不是产品名
    "url": "https://github.com/apple/swift-collections.git",
    "kind": "upToNextMajorVersion",
    "minimumVersion": "1.3.0"
}

✅ 正确配置：

{
    "name": "Collections",  // 正确：这是 Package.swift 中 products 的 name
    "url": "https://github.com/apple/swift-collections.git",
    "kind": "upToNextMajorVersion",
    "minimumVersion": "1.3.0"
}

SPM 依赖库版本要求读取

1. 核心定义位置：Package.swift 的 platforms 字段

每个 Swift 包在根目录下有一个 Package.swift，其中包含平台支持声明：

let package = Package(
    name: "SomeLibrary",
    platforms: [
        .iOS(.v12),        // 最低支持 iOS 12
        .macOS(.v10_14),   // 最低支持 macOS 10.14
        .tvOS(.v13)        // 最低支持 tvOS 13
    ],
    products: [
        .library(name: "SomeLibrary", targets: ["SomeLibrary"])
    ],
    // ... 其他配置
)

2. 版本声明说明

• .iOS(.v12) 表示：该包最低支持 iOS 12 及以上版本
• 默认行为：如果没有声明 platforms，表示默认兼容 iOS 8 及以上（SwiftPM 默认最低 iOS 8）
• 现代包特点：大多数现代包都会显式声明最低版本要求