Question 1

如何修复在 Linux 上使用 xtool 登录 Apple ID 时出现的 CERTIFICATE_VERIFY_FAILED 错误？

Accepted Answer

出现此错误的原因是：`gsd.apple.com`（登录流程中使用）提供的证书链终止于 **Apple Root CA - G3**，而该证书未包含在 Ubuntu 的 `ca-certificates` 证书包中（macOS 通过系统钥匙串信任该证书，因此此问题仅出现在 Linux 上）。xtool 的 `Client.tlsConfiguration` 只将 2006 年的 Apple Root CA 添加到了 `additionalTrustRoots`。

**修复方法：** 在 `Sources/XKit/HTTPClientProtocol/AsyncHTTPClient+HTTP.swift` 中将 Apple Root CA - G3 添加到受信任的根证书中：

```swift
// gsd.apple.com chains to Apple Root CA - G3 (not the 2006 Apple Root CA).
// swiftlint:disable:next force_try
let appleRootG3CA = try! NIOSSLCertificate(bytes: Array(appleRootG3PEM.utf8), format: .pem)
tlsConfiguration.additionalTrustRoots = [.certificates([appleRootCA, appleRootG3CA])]
```

从 https://www.apple.com/certificateauthority/AppleRootCA-G3.cer 下载证书，并将其作为 `private let appleRootG3PEM = """ ... """` 常量嵌入。请验证 SHA-256 指纹：`63:34:3A:BF:B8:9A:6A:03:EB:B5:7E:9B:3F:5F:A7:BE:7C:4F:5C:75:6F:30:17:B3:A8:C4:88:C3:65:3E:91:79`。

**验证修复：**
```bash
openssl s_client -connect gsd.apple.com:443 -servername gsd.apple.com -CAfile AppleRootCA-G3.pem
# 应显示：Verify return code: 0 (ok)
```

重新构建后，登录即可通过 TLS 握手阶段（虚假账号现在会收到 `-20101` 错误而非握手错误，真实的 Apple ID 则可以成功登录）。

Question 2

如何修复 xtool 设置过程中出现的“Error: Key is invalid: invalidPEMDocument”错误？

Accepted Answer

此错误发生在身份验证过程中提供了错误的文件路径时。输入 Key ID 和 Issuer ID 后，xtool 会要求你提供 `AuthKey.p8` 文件（从 App Store Connect 下载）的路径——而不是 `Xcode.xip` 文件。如果你错误地传入了 Xcode.xip 路径，就会得到 `invalidPEMDocument` 错误，因为它不是有效的 PEM/AuthKey 文件。解决方法：重新运行设置，并在提示输入密钥时提供 `AuthKey_XXXXXXXXXX.p8` 的完整路径。身份验证完成后，系统会单独询问你 `Xcode.xip` 的路径。

Question 3

如何修复在 Linux 上使用 Xcode 27 / iOS 27 SDK 构建时出现的 'unknown architecture' 和 'undefined symbol: main' 链接器错误？

Accepted Answer

捆绑的 LLD 20 链接器无法解析 iOS 27 SDK 的 `.tbd` stub 文件中声明的 `arm64e.x1-ios` 目标，因此解析 `libSystem.tbd` 失败，随后误导性地报告 `undefined symbol: main` —— 你的代码没有问题。**正确的修复方法：** 更新 xtool —— 该问题已在上游通过 PR #270 修复，此 PR 将 LLVM 补丁（llvm/llvm-project#222721）引入了 darwin-tools-linux-llvm，更新后重新运行 `xtool sdk install`。**适用于 xtool ≤1.20.0 的变通方法：** 从 SDK 中全部 675 个 `.tbd` 文件里移除这个无法识别的目标，然后重新构建：`grep -rl 'arm64e\.x1-ios' "$SDK_ROOT" | while read -r f; do sed -i 's/, *arm64e\.x1-ios//g; s/arm64e\.x1-ios, *//g; s/arm64e\.x1-ios//g' "$f"; done`。注意，每次执行 `xtool sdk install` 之后都必须重新应用此修改。用 Swift 工具链的 LLD 21 替代是行不通的（`This version of lld does not support linking for platform iOS`）。

Question 4

如何修复在使用密码运行 xtool auth login 时来自 GsService2 的 HTTP 503 错误？

Accepted Answer

这是 xtool v1.23.0 及更早版本中的一个已知 bug:Apple 的边缘服务器会在验证凭据之前,基于客户端标识请求头拒绝登录请求。该修复已在 xtool v1.24.0 中发布(通过 PR #406)。请将 xtool 升级到 v1.24.0 或更高版本,然后再次运行 `xtool auth login`。注意:此 503 错误与 anisette 服务器或您的网络/凭据无关——升级是唯一的解决办法。

Question 5

如何修复在 Linux 上使用 xtool 构建时出现的 'arm_neon.h __builtin_bit_cast source type int does not match int64_t' 错误？

Accepted Answer

出现这种情况是因为 `xtool sdk install` 会从 PATH 中找到的 `clang`(例如 Clang 22)复制 Clang 资源头文件,而你的 Swift 工具链内嵌的是较旧版本的 Clang(Swift 6.4 内嵌 Clang 21)。不匹配的头文件会导致编译失败。变通方法:用与 Swift 内嵌 Clang 版本相匹配的头文件替换 SDK 的资源头文件。对于 Swift 6.4(Clang 21),安装 `clang21`(例如在 Arch 上:`pacman -S clang21`,提供 21.1.8),并将其头文件复制到已安装的 SDK include 目录:复制 `/usr/lib/llvm21/lib/clang/21/include` 以替换 SDK 的 `usr/lib/clang/21/include` 中的内容。完成此操作后,`arm_neon.h`/`_Builtin_intrinsics` 错误会消失,构建得以继续。要检查你的 Swift 内嵌的是哪个 Clang,可在工具链中查找 `libclang.so.21.0.0`。从长远来看,xtool 应使用工具链自带的头文件,或者因版本不匹配而报错(该问题在 issue #273 中跟踪)。

xtool

核心功能

避坑指南

适用场景

标签

快速上手

相似推荐