xtool 在 Linux/Windows 上安装配置指南:用 SwiftPM 在 Linux 构建与部署 iOS 应用
xtool 在 Linux/Windows 上安装配置指南:用 SwiftPM 在 Linux 构建与部署 iOS 应用
xtool 是一款跨平台(Linux/WSL/macOS)的 Xcode 替代品(仓库 README 中的定位是 "Cross-platform Xcode replacement"),它允许开发者在 Linux 或 Windows(通过 WSL)上完全脱离 Xcode 图形界面,用标准的 SwiftPM 工作流构建、签名并把 iOS 应用安装到真机。本文以官方文档 Installation-Linux.md 为骨架,结合仓库源码逐步讲解从环境准备、下载安装 xtool、登录 Apple Developer Services、构建 Darwin Swift SDK 到最终用 xtool dev 跑通第一个应用的完整流程,读完即可在自己的 Linux 机器上完成一次真实的 iOS 开发闭环。
安装路线总览
Linux/Windows 上的安装可以归纳为三个阶段:
- 准备前置条件:Windows 用户先配置 WSL 与 USB 透传;然后安装 Swift 6.4 工具链、usbmuxd,并下载
Xcode.xip; - 安装 xtool 本体:从官方 Release 下载对应架构的
xtool.AppImage,放入PATH; - 一次性配置:运行
xtool setup,依次完成登录(API Key 或密码两种模式)和从Xcode.xip生成 iOS Swift SDK 两步。
从源码看,xtool setup 正是后两步的组合。在 SetupCommand.swift 中,setup 子命令的 discussion 明确写着:"Authenticates with Apple if needed, then adds the iOS SDK to SwiftPM. Equivalent to running xtool auth && xtool sdk"。也就是说,你完全可以分别执行 xtool auth 与 xtool sdk 来达到同样的效果。
整个 CLI 的顶层结构可在 XTool.swift 与 README.md 中看到:setup、auth、sdk 属于 Configuration 组,new、dev、ds 属于 Development 组,devices、install、uninstall、launch 属于 Device 组,覆盖了从建项目到装应用的全链路。
前置条件一:Windows 用户准备 WSL 与 USB 透传
如果你在 Windows 上开发,官方推荐的路径是借助 Windows Subsystem for Linux(WSL),让 xtool 运行在 WSL 的 Linux 发行版中。
- 安装 WSL:按微软官方指南安装 WSL 及你喜欢的 Linux 发行版;
- 配置 USB 透传(USBIPD):为了让 WSL 内的 xtool 能通过 USB 访问 iOS 设备,需要按照微软的 USBIPD 安装指引完成 USB 设备直通设置,确保能把 iOS 设备绑定到 WSL;
- 验证设备可见:安装完成后,可在 WSL 内用
usbmuxd相关工具确认设备已被识别(见下文)。
常见错误:AFCClient.Error.muxError
如果在后续流程中遇到 Error: AFCClient.Error.muxError,说明 USBIPD 的直通没有生效。社区给出的替代方案是:通过 Windows 上的 iTunes 中转设备连接,而不是依赖 USBIPD。即让 Windows 的 iTunes 持有 usbmux 会话,再由 WSL 内的 xtool 经由该通道与设备通信。文档中提供了对应 issue 评论的完整处理步骤,遇到该报错时按此思路排查即可。
前置条件二:安装 Swift 6.4 工具链
xtool 依赖 Swift 工具链在 Linux 上执行 SwiftPM 构建,因此需要从 Swift 官方为 Linux 发行版准备的安装包中安装 Swift 6.4。安装完成后验证版本:
swift --version
# 应输出类似:
# Swift version 6.4 (swift-6.4-RELEASE)
为什么必须是 6.4 而不是更早的版本?这在源码中有明确证据:DevBSPCommand.swift 在运行构建服务器前会检查
SwiftVersion.current.supportsSwiftBuild,不满足时直接报错 "xtool dev build-serverrequires Swift 6.4 or later";而 SDKBuilder.swift 的注释也说明,SwiftPM 的 swiftbuild 后端在解析 librarian 与 linker 路径时存在 bug,Swift 6.3 及以下无法正确解析这些路径,因此 6.4 是硬性要求。
前置条件三:安装 usbmuxd
xtool 在 Linux 上与 iOS 设备通信的底层通道是 usbmuxd(libimobiledevice 项目的一部分)。你的发行版可能已经预装,先检查:
usbmuxd --help
# Usage: usbmuxd [OPTIONS]
# ...
如果提示 "command not found",则需自行安装。Ubuntu/Debian 上执行:
sudo apt-get install usbmuxd
推荐的辅助工具:libimobiledevice-utils
usbmuxd 之外,libimobiledevice 项目还提供一批命令行工具,其中 ideviceinfo 可以在命令行直接查看设备信息,常用于确认设备是否已正确连接。Ubuntu/Debian 上安装:
sudo apt-get install libimobiledevice-utils
# The following NEW packages will be installed:
# libimobiledevice-utils
# 0 upgraded, 1 newly installed
ideviceinfo
# DeviceName: Kabir's iPhone
# SerialNumber: ...
# UniqueDeviceID: ...
# ...
仓库中 xtool 与设备的通信正是建立在 usbmuxd 之上:ConnectionManager.swift 负责搜索与连接设备,DevicesCommand.swift 则通过 ClientDevice.search 列出设备,并支持在设备未连接时持续等待。
前置条件四:下载 Xcode.xip
xtool 在 Linux 上并不需要完整的 Xcode 来构建,但仍需要 Xcode 中的 iOS SDK 与工具链内容 来生成 Swift SDK,而官方只以 Xcode.xip 形式分发。因此需要:
- 从 Apple 开发者网站(developer.apple.com/download/all)下载 Xcode 27;
- 记下
Xcode.xip的保存路径,后续配置 SDK 时会用到。
注意:上述下载地址需要登录 Apple ID 并接受许可协议,请在浏览器中完成下载,而不是用
curl直接拉取。
第一步:下载并安装 xtool(AppImage)
安装好前置条件后,下载对应架构的 xtool.AppImage。官方 Release 提供按 CPU 架构命名的产物,重命名为 xtool 后放入 PATH 中任一目录:
curl -fL \
"https://github.com/xtool-org/xtool/releases/latest/download/xtool-$(uname -m).AppImage" \
-o xtool
chmod +x xtool
sudo mv xtool /usr/local/bin/
$(uname -m) 会自动展开为当前机器的架构(x86_64 / aarch64),因此上述命令在不同机器上可直接复用。
AppImage 的运行机制:从 Linux/build.sh 可以看到,xtool 的 Linux 发布包是用 linuxdeploy 工具把编译好的二进制、desktop 文件与图标打包成
xtool-${curr_arch}.AppImage的。AppImage 默认依赖 FUSE 挂载运行;如果你的环境不支持 FUSE(例如容器内),可以设置环境变量APPIMAGE_EXTRACT_AND_RUN=1让其解包后运行——build.sh 自身在检测不到fusermount时正是这样处理的。
验证安装是否成功:
xtool --help
# OVERVIEW: Cross-platform Xcode replacement
# ...
若看到上述概览信息,说明 CLI 已就绪。
第二步:一次性配置——xtool setup 与登录
执行一次性配置命令:
xtool setup
如开头所述,这一步等价于 xtool auth && xtool sdk(见 SetupCommand.swift)。它首先引导你登录 Apple Developer Services,界面如下:
Select login mode
0: API Key (requires paid Apple Developer Program membership)
1: Password (works with any Apple ID but uses private APIs)
Choice (0-1):
两种登录模式如何选择
模式 0:API Key(推荐给付费开发者)
如果你已加入付费的 Apple Developer Program,这是官方推荐的模式。它基于公开的 App Store Connect API,安全且稳定。你需要按 Apple 的指引生成一个 Team Key(角色为 App Manager),然后提供以下三项(对应 AuthCommand.swift 中 logInWithKey 的交互流程):
- Key ID;
- Issuer ID;
- Key path(
.p8私钥文件路径)。
源码中会对该私钥做严格校验:用 P256.Signing.PrivateKey(pemRepresentation:) 解析 PEM,解析失败会直接报错 "Key is invalid"。成功后将生成 AuthToken.appStoreConnect 形式的凭据(保存了 id、issuerID 与 PEM 内容)。
模式 1:Password(任何 Apple ID 可用,但走私有 API)
未加入付费开发者计划时使用。该模式依赖 Apple 的私有 API 完成认证,源码注释(AuthCommand.swift)明确说明其原理是"模拟一台 Pixel 手机/Windows PC 来与 Apple 服务交互",因此:
- 建议使用不重要的备用 Apple ID(throwaway Apple ID)以降低风险;
- 交互流程依次是:Apple ID、密码(输入不回显)、双因素认证(2FA),随后会列出你的开发团队并让你选择(AuthCommand.swift 中
DeveloperServicesLoginManager.logIn+DeveloperServicesListTeamsRequest); - 成功后生成
AuthToken.xcode凭据(包含 adsid、token、过期时间、teamID 等)。
无论哪种模式,你的凭据只会发给 Apple,不会发往任何其他方——源码中 AuthToken.swift 显示凭据通过本地 KeyValueStorage 以 XTLAuthToken 键保存,且项目完全开源,你完全可以自行从源码构建并审计这一行为。
补充:登录相关命令也可单独使用。
xtool auth下还有login(重新登录)、logout、status子命令;logout还支持--reset-2fa标志,用于重置 xtool 作为"伪设备"的 2FA 数据,下次登录时需重新完成双因素认证。
第三步:配置 SDK——从 Xcode.xip 生成 Darwin Swift SDK
登录完成后,setup 会继续询问 Xcode.xip 的路径:
Choice (0-1): 0
...
Path to Xcode.xip:
输入之前记录的路径(例如 ~/Downloads/Xcode_27.0.xip)并回车,xtool 会解压该 XIP,从中抽取 iOS/macOS SDK 并组装成一个 SwiftPM 可用的 Darwin Swift SDK,自动安装到 SwiftPM 的 SDK 目录中。
底层发生了什么
SDKBuilder.swift 完整实现了这条流水线,主要包含:
- 输入校验:SDKBuilder.Input 会检查路径是否存在,若是文件则校验 XIP 魔数是否为
xar!,若是目录则校验是否包含Contents/Developer(从而兼容直接传入解压后的Xcode.app); - 解压 XIP:通过
XIP.transform → Chunks.transform → Files.transform的流式管线解包,并实时打印[Extracting XIP]进度; - 裁剪与组装:只保留构建所需的子集(
Toolchains/.../usr/lib/swift、Platforms/{iPhoneOS,MacOSX,iPhoneSimulator}等),然后生成swift-sdk.json(含arm64-apple-ios、arm64-apple-ios-simulator、arm64-apple-macosx等 target triple)、toolset.json(指定ld64.lld链接器与llvm-lib库管理器)和info.json元数据; - 集成工具链:从 darwin-tools 仓库拉取 Linux 版 LLVM 工具集,并注册 OpenAppleMacros 作为
swift-plugin-server,用于在 Linux 上支持 SwiftUI/Foundation 相关宏。
生成的 SDK 被安装为 darwin.artifactbundle。从 DarwinSDK.swift 可以看到它的存放位置遵循 SwiftPM 规范:默认在 ~/.swiftpm/swift-sdks/,如果你设置了 XDG_CONFIG_HOME 环境变量则在 $XDG_CONFIG_HOME/swiftpm/swift-sdks/。
验证 SDK 是否就绪
swift sdk list
# darwin
输出中出现 darwin 即表示 SDK 已注册到 SwiftPM。此外,xtool sdk 还提供一组管理子命令(见 SDKCommand.swift):
| 子命令 | 作用 |
|---|---|
xtool sdk install [--slim] <path> |
安装 SDK,接受 Xcode.xip、Xcode.app 或预构建的 darwin.xtoolsdk;--slim 生成精简版 |
xtool sdk update |
就地更新已安装的 normal 版 SDK(slim 版不可就地更新) |
xtool sdk remove |
卸载已安装的 SDK |
xtool sdk status |
查看 SDK 路径、flavor(slim/normal/legacy)与版本 |
xtool sdk build <xip> <dir> |
在自定义目录中构建 SDK 包 |
关于 slim 与 normal 两种 SDK 形态:DarwinSDK.swift 中
Flavor枚举说明了区别——slim 版占用磁盘空间更小,但不保留完整 Xcode.app,因此无法就地自动更新;normal 版包含完整副本、占用更大,但可支持xtool sdk update原地升级。当 SDK 过期时,slim 版会提示你重新xtool sdk install,normal 版则会自动重建(见 SDKCommand.swift 的EnsureSDKOperation)。
验证安装:创建并运行你的第一个应用
至此环境配置完成。接下来按官方教程 First-app.tutorial 走一遍 "Hello World" 即可验证整条链路:
- 创建项目:
xtool new Hello。从 NewCommand.swift 可以看到它会生成一个标准的 SwiftPM 包(含Package.swift、xtool.yml、Sources/Hello/HelloApp.swift、ContentView.swift等),并自动生成.bsp/xtool.json供 IDE 通过 Build Server Protocol 获得补全与文档能力; - 连接设备:用 USB 连接 iOS 设备,可通过
ideviceinfo(前置条件三中安装)确认设备可见; - 构建并安装:在包目录内运行
xtool dev。首次运行 SwiftPM 需要为 iOS SDK 编译 Swift Modules,耗时较长,之后会利用全局缓存显著提速; - 完成首次配对:设备上会弹出 "Trust" 对话框,点按信任并输入锁屏密码;若此时报错,重新运行
xtool dev即可; - 自动注册与签名:xtool 会连接 Apple Developer Services,自动注册设备、生成证书/App ID/描述文件(Provisioning Profile)、签名并安装应用(对应 DevCommand.swift 中
IntegratedInstaller.install的完整流程)。之后如需设备开启 Developer Mode,按提示在设置中打开后重试; - 首次启动:应用出现在主屏幕后,如遇 "Untrusted Developer" 提示,到 设置 → 通用 → VPN 与设备管理 中信任你的开发者证书即可正常启动。
如果你只是想在构建阶段验证,也可以使用 xtool dev build(仅构建 .app/.ipa)或 xtool dev run(构建并安装到设备)等子命令。
进阶提示与常见问题
- 在容器中使用:官方仓库提供了 Dockerfile 与 Linux/README.md。容器内访问真机时,需要在宿主机把 usbmuxd 转发到端口(如
socat TCP-LISTEN:27015 ... UNIX-CLIENT:/var/run/usbmuxd),并让容器内的 libusbmuxd 连接该端口; - SDK 版本管理:SDK 的构建逻辑会随 xtool 演进(源码中以
sdkEpoch标记),当xtool sdk status显示的版本与当前 xtool 要求不一致时,按 SDKCommand.swift 的逻辑更新或重装即可; - IDE 支持:
xtool new生成的.bsp/xtool.json告诉 VS Code 等编辑器通过xtool dev build-server(Swift 6.4+ 可用)提供构建信息与语法高亮;若不想自动生成该文件,可在xtool.yml中设置skipLSP: true(见 LSPConfig.swift)。
按照本文完成全部步骤后,你已拥有一套完全运行在 Linux/WSL 上的 iOS 开发环境:SwiftPM 负责构建,xtool 负责打包、签名与部署,全程无需 macOS 或 Xcode 图形界面。