手动安装 KXBuild

一键脚本在你的环境里跑不通、想自己决定每个组件的版本和位置，或者内网离线部署——那就照下面的步骤自己装。装的东西和脚本完全一样。

要装什么

所有组件都放在一个安装根目录下，下文叫它 KXBUILD_HOME：Windows 默认 %USERPROFILE%\kxbuild，Linux / macOS 默认 ~/kxbuild。换个目录也行，但后面每一步都要跟着改。

组件	干什么用	装到哪	谁来装
kxbuild	命令行主程序，其余组件都由它调度	KXBUILD_HOME/bin/	你
C++ 编译环境	Swift 工具链和 CocoaPods 的原生扩展要靠它编译	Windows：Visual Studio C++ 生成工具；Linux：gcc / make 等系统包；macOS：Xcode 命令行工具	你
Ruby + CocoaPods	iOS 工程的依赖管理	KXBUILD_HOME/ruby/，或者用系统里已有的	Windows 上你装 Ruby、doctor 装 CocoaPods；Linux / macOS 都自己装
Node.js ≥ 20	React Native / Expo 工程需要，别的技术栈用不到	KXBUILD_HOME/node/，或者用系统里已有的	你
Swift 工具链	编译 Swift / Objective-C 代码。版本必须和 iOS SDK 要求的一致	KXBUILD_HOME/Developer/Toolchains/（macOS 有 Xcode 时直接用 Xcode 的）	你
iOS SDK 及其他组件	iPhoneOS SDK、xcrun / ld64.lld / clang 等一系列工具	KXBUILD_HOME/Developer/Platforms/ 等	kxbuild doctor

Swift 版本必须是：这是最后一步 doctor 下载的 iOS SDK 所用的版本，两者必须严格一致。Apple 工具链库由 doctor 随 SDK 一并安装，不需要再做别的。下载失败时手动放置的方法见 iOS SDK。

Windows 默认有 260 字符的路径长度限制，KXBUILD_HOME 别放太深；下面的命令都以默认的 %USERPROFILE%\kxbuild 为例。所有 PowerShell 命令请在管理员窗口里执行。

Visual Studio C++ 生成工具 + Windows SDK

Swift 在 Windows 上通过 MSVC 编译、链接 Windows SDK，所以要先装这个。从 VS 官网下载并勾选「C++ 的桌面开发」，或者直接执行：

PS> winget install --id Microsoft.VisualStudio.2022.BuildTools --override "--quiet --wait --norestart --add Microsoft.VisualStudio.Workload.VCTools --includeRecommended"

占用 10-20 GB 磁盘。已经装过 Visual Studio 的，打开 Visual Studio Installer 补上「C++ 的桌面开发」工作负载即可。

下载 kxbuild

下载对应架构的压缩包，把里面的 kxbuild.exe 放到 %USERPROFILE%\kxbuild\bin\：

Windows x64 Windows ARM64

PS> New-Item -ItemType Directory -Force "$env:USERPROFILE\kxbuild\bin" | Out-Null
PS> Expand-Archive -Force "$env:USERPROFILE\Downloads\kxbuild.zip" "$env:TEMP\kxbuild"
PS> Move-Item -Force (Get-ChildItem "$env:TEMP\kxbuild" -Recurse -Filter kxbuild.exe)[0].FullName "$env:USERPROFILE\kxbuild\bin\kxbuild.exe"

下载下来的文件名可能带版本号，命令里的 kxbuild.zip 按实际改。链接始终指向最新版本，版本号无所谓：装完后 kxbuild doctor 会自动升级。

Ruby + DevKit

CocoaPods 是带原生扩展的 Ruby gem，所以要装带 DevKit 的版本。从 rubyinstaller.org 下载「Ruby+Devkit 3.4.x (x64)」，安装目录选 %USERPROFILE%\kxbuild\ruby，装完在 PowerShell 里执行：

PS> & "$env:USERPROFILE\kxbuild\ruby\bin\ridk.cmd" install 1 3

ridk install 1 3 装的是 MSYS2 基础环境和 MinGW 编译工具链，几百 MB。系统里已经有带 ridk 的 Ruby 可以跳过这一步；CocoaPods 本身由 kxbuild doctor 安装。

Node.js ≥ 20

只有 React Native / Expo 工程用得到。系统里已经有 v20 以上的 node 就不用装；否则从 nodejs.org 下载 LTS 的 .zip（不是 .msi），解压后把里面的文件放到：

%USERPROFILE%\kxbuild\node\ （node.exe 直接在这一层）

用 .zip 是为了不碰系统已有的 node；如果不介意全局安装，直接跑 .msi 也行，第 6 步就不用把 node 加进 PATH。

Swift 工具链

从 swift.org 下载 SDK 要求的版本（见页首说明），装到 %USERPROFILE%\kxbuild\Developer，只装 NoAsserts 工具链：

PS> & "$env:USERPROFILE\Downloads\swift--RELEASE-windows10.exe" /quiet /norestart InstallRoot="$env:USERPROFILE\kxbuild\Developer" OptionsInstallAssertsToolchain=0 OptionsInstallNoAssertsToolchain=1

下载约 1.7 GB，装完约 4.5 GB。ARM64 机器把文件名里的 windows10 换成 windows10-arm64。默认的 +Asserts 工具链会在每次编译时跑编译器自检，只会更慢，所以选 NoAsserts。

环境变量

写入用户环境变量 KXBUILD_HOME，并把 bin、node、ruby\bin 加到 PATH 前面：

PS> [Environment]::SetEnvironmentVariable('KXBUILD_HOME', "$env:USERPROFILE\kxbuild", 'User')
PS> [Environment]::SetEnvironmentVariable('PATH', "$env:USERPROFILE\kxbuild\bin;$env:USERPROFILE\kxbuild\node;$env:USERPROFILE\kxbuild\ruby\bin;" + [Environment]::GetEnvironmentVariable('PATH', 'User'), 'User')

用系统里已有的 node / ruby 的话，把对应那段从 PATH 里去掉。改完要新开一个终端才生效。

跑 kxbuild doctor 装剩下的

新开一个管理员 PowerShell，执行：

PS> kxbuild doctor

doctor 会检查前面每一步，然后安装 sharedcomponents 里的 iOS SDK，通过 kpm 下载 CocoaPods 和其余工具，并开启 Windows 开发者模式和长路径支持（所以需要管理员）。哪一步没装对，它会指出来。

下面以 x86_64 和 ~/kxbuild 为例。WSL 里的 Ubuntu 完全照 Linux 的步骤来；注意别用 Windows 那边的 node（/mnt/c/...），它跑不了 Linux 工具。

系统编译包

gcc / make / cmake 等基础工具，加上 Swift 工具链运行需要的共享库。Debian / Ubuntu：

$ sudo apt-get update && sudo apt-get install -y build-essential cmake rsync zip unzip git binutils gnupg2 libc6-dev libcurl4-openssl-dev libedit2 libpython3-dev libsqlite3-0 libxml2-dev libncurses-dev libz3-dev pkg-config tzdata zlib1g-dev

Fedora / RHEL：

$ sudo dnf install -y gcc gcc-c++ make cmake rsync zip unzip git binutils libcurl-devel libedit-devel libicu-devel sqlite-devel python3-devel libuuid-devel libxml2-devel zlib-devel

其他发行版对照 swift.org 的 Linux 安装页装齐依赖即可。

下载 kxbuild

下载压缩包，把里面的 kxbuild 放到 ~/kxbuild/bin/（arm64 机器把地址里的 amd64 改成 arm64）：

$ mkdir -p ~/kxbuild/bin /tmp/kxbuild
$ curl -fsSL -o /tmp/kxbuild.zip "https://kpm.kxbuild.net/latest/kxbuild/kxbuild?platform=linux&arch=amd64"
$ unzip -oq /tmp/kxbuild.zip -d /tmp/kxbuild
$ install -m 755 "$(find /tmp/kxbuild -type f -name kxbuild | head -n 1)" ~/kxbuild/bin/kxbuild

链接始终指向最新版本；装完后 kxbuild doctor 会自动升级。

Ruby + CocoaPods

最省事的做法是用发行版的 Ruby 全局装 CocoaPods：

$ sudo apt-get install -y ruby-full && sudo gem install cocoapods --no-document

不想动系统 Ruby 的话，可以像一键脚本那样把 portable-ruby 解压到 ~/kxbuild/ruby，用 GEM_HOME=~/kxbuild/ruby/gems 装 CocoaPods，再在 ~/kxbuild/bin/pod 写一个先设置 GEM_HOME 再调用 ruby gems/bin/pod 的包装脚本。只要 PATH 里能找到 pod 就行。

Node.js ≥ 20

只有 React Native / Expo 工程用得到。node -v 已经是 v20 以上就跳过；否则把 nodejs.org 的 LTS 解压到 ~/kxbuild/node（版本号换成当前 LTS）：

$ mkdir -p ~/kxbuild/node && curl -fsSL https://nodejs.org/dist/v24.21.0/node-v24.21.0-linux-x64.tar.gz | tar -xz -C ~/kxbuild/node --strip-components=1

Swift 工具链

用 swift.org 官方的工具链管理器 swiftly 安装，把它和工具链都放进 ~/kxbuild（kxbuild 会扫描 Developer/Toolchains 这个目录）：

$ export SWIFTLY_HOME_DIR=~/kxbuild/swiftly SWIFTLY_BIN_DIR=~/kxbuild/swiftly/bin SWIFTLY_TOOLCHAINS_DIR=~/kxbuild/Developer/Toolchains
$ mkdir -p "$SWIFTLY_BIN_DIR" "$SWIFTLY_TOOLCHAINS_DIR" /tmp/swiftly
$ curl -fsSL "https://download.swift.org/swiftly/linux/swiftly-$(uname -m).tar.gz" | tar -xz -C /tmp/swiftly
$ /tmp/swiftly/swiftly init --assume-yes --skip-install --no-modify-profile
$ "$SWIFTLY_BIN_DIR/swiftly" install  --use --assume-yes

工具链约 1 GB。swiftly 装完如果提示还缺系统库，照它给的命令 sudo 装上。

环境变量

把下面内容存为 ~/kxbuild/env.sh：

export KXBUILD_HOME="$HOME/kxbuild"
export SWIFTLY_HOME_DIR="$KXBUILD_HOME/swiftly"
export SWIFTLY_BIN_DIR="$KXBUILD_HOME/swiftly/bin"
export SWIFTLY_TOOLCHAINS_DIR="$KXBUILD_HOME/Developer/Toolchains"
export PATH="$KXBUILD_HOME/node/bin:$KXBUILD_HOME/bin:$SWIFTLY_BIN_DIR:$KXBUILD_HOME/ruby/bin:$PATH"

然后让 shell 启动时加载它（zsh 改成 ~/.zshrc）：

$ printf '\n# kxbuild\n. "$HOME/kxbuild/env.sh"\n' >> ~/.bashrc && . ~/kxbuild/env.sh

用系统 node / ruby 的，把对应目录从 PATH 里去掉就行，目录不存在也无妨。

跑 kxbuild doctor 装剩下的

$ kxbuild doctor

doctor 会检查前面每一步，然后安装 sharedcomponents 里的 iOS SDK，并通过 kpm 下载其余组件。哪一步没装对，它会指出来。

装了完整 Xcode 的 Mac 直接用 Xcode 的 Swift 工具链，第 5 步跳过。下面以 Apple Silicon 和 ~/kxbuild 为例。

Xcode 命令行工具

没装 Xcode 的话至少要有命令行工具（clang、git、make 都在里面）：

$ xcode-select --install

会弹出系统对话框，按提示装完再继续。

下载 kxbuild

下载压缩包，把里面的 kxbuild 放到 ~/kxbuild/bin/（Intel 机器把地址里的 arm64 改成 amd64）：

$ mkdir -p ~/kxbuild/bin /tmp/kxbuild
$ curl -fsSL -o /tmp/kxbuild.zip "https://kpm.kxbuild.net/latest/kxbuild/kxbuild?platform=darwin&arch=arm64"
$ unzip -oq /tmp/kxbuild.zip -d /tmp/kxbuild
$ install -m 755 "$(find /tmp/kxbuild -type f -name kxbuild | head -n 1)" ~/kxbuild/bin/kxbuild

链接始终指向最新版本；装完后 kxbuild doctor 会自动升级。

CocoaPods

有 Homebrew 直接装：

$ brew install cocoapods

没有 Homebrew 的，用系统 Ruby sudo gem install cocoapods，或者按 Linux 那一页的做法把 portable-ruby 放进 ~/kxbuild/ruby。只要 PATH 里能找到 pod 就行。

Node.js ≥ 20

只有 React Native / Expo 工程用得到。node -v 已经是 v20 以上就跳过，否则：

$ brew install node

或者从 nodejs.org 下载 LTS 的 .pkg 安装；想放进 ~/kxbuild/node 的话，照 Linux 那一页用 tar 解压 darwin-arm64 的包。

Swift 工具链（没有 Xcode 时）

用 swiftly 安装 SDK 要求的版本，工具链放进 ~/kxbuild/Developer/Toolchains：

$ export SWIFTLY_HOME_DIR=~/kxbuild/swiftly SWIFTLY_BIN_DIR=~/kxbuild/swiftly/bin SWIFTLY_TOOLCHAINS_DIR=~/kxbuild/Developer/Toolchains
$ mkdir -p "$SWIFTLY_BIN_DIR" "$SWIFTLY_TOOLCHAINS_DIR"
$ curl -fsSL -o /tmp/swiftly.pkg https://download.swift.org/swiftly/darwin/swiftly.pkg
$ installer -pkg /tmp/swiftly.pkg -target CurrentUserHomeDirectory
$ ~/.swiftly/bin/swiftly init --assume-yes --skip-install --no-modify-profile
$ "$SWIFTLY_BIN_DIR/swiftly" install  --use --assume-yes

工具链约 1 GB。

环境变量

把下面内容存为 ~/kxbuild/env.sh。注意 bin 放在 PATH 末尾：系统自带的 xcrun / codesign 必须优先于 kxbuild 的同名替身：

export KXBUILD_HOME="$HOME/kxbuild"
export SWIFTLY_HOME_DIR="$KXBUILD_HOME/swiftly"
export SWIFTLY_BIN_DIR="$KXBUILD_HOME/swiftly/bin"
export SWIFTLY_TOOLCHAINS_DIR="$KXBUILD_HOME/Developer/Toolchains"
export PATH="$KXBUILD_HOME/node/bin:$PATH:$KXBUILD_HOME/bin:$SWIFTLY_BIN_DIR:$KXBUILD_HOME/ruby/bin"

然后让 shell 启动时加载它：

$ printf '\n# kxbuild\n. "$HOME/kxbuild/env.sh"\n' >> ~/.zprofile && . ~/kxbuild/env.sh

跑 kxbuild doctor 装剩下的

$ kxbuild doctor

doctor 会检查前面每一步，然后安装 sharedcomponents 里的 iOS SDK，并通过 kpm 下载其余组件。哪一步没装对，它会指出来。

装的过程中卡住了？先跑一遍 kxbuild doctor 看它怎么说；还是不行就发邮件到 admin@kxbuild.net，带上 doctor 的输出。