kxbuild 命令参考

kxbuild 的全部子命令与参数，包括 doctor、build、resolve、project、update、version。

用法 kxbuild <命令> [参数]。kxbuild 负责工程与构建，手机相关操作由 kxdevice 负责。每条命令都有 --help。全局参数 --json 输出机器可读的 JSON，供脚本和插件使用，排错时不要加，错误详情只在普通输出中。

> kxbuild version

命令总表

命令	作用
doctor [工程]	检查并修复开发环境，带工程路径时做工程级准备
build <工程>	编译并打包，可选安装到手机
resolve <工程>	解析 Swift Package 依赖
project …	查看、新建、编辑、转换工程
update	升级 kxbuild 到最新版并自动体检
version	版本信息

doctor

kxbuild doctor [工程] [-v]

检查并修复开发环境，Windows 上还会打开开发者模式和长路径支持。带工程路径时识别工程类型并完成对应准备，Flutter、React Native、Expo、Kotlin Multiplatform、cocos2d-x 工程第一次编译前必须运行。

安装后、升级后、构建或调试报错时，先运行一次 doctor，多数环境问题它会直接修好。仍失败见常见问题排查。

参数	说明
-v, --verbose	显示每一步和子进程输出，排错时使用

> kxbuild doctor

> kxbuild doctor D:\projects\my_flutter_app -v

build

kxbuild build <project.xcodeproj | project.xcworkspace | 包目录> [参数]

编译并打包 Xcode 工程、工作区或含 Package.swift 的目录。未指定 scheme 或 target 时构建默认的。使用 CocoaPods 的工程构建 .xcworkspace。典型用法见构建与配置。

构建对象

参数	说明
-s, --scheme NAME	构建这个 scheme
-t, --target NAME	构建这个 target
-c, --config NAME	构建配置，默认为 scheme 的运行配置，没有 scheme 时为 Debug
--sdk NAME	SDK，iphoneos、iphonesimulator 或 macosx
--arch ARCH	只构建这个架构，arm64 或 x86_64
--toolchain NAME	指定工具链，名字或标识符
--ignoreDependence	只构建指定的 target，不带依赖

构建设置

参数	说明
-D, --setting KEY=VALUE	覆盖一个构建设置，可重复，优先级与 xcodebuild 的 KEY=VALUE 相同
--xcconfig PATH	套用 .xcconfig 文件中的设置，同 xcodebuild -xcconfig

输出与产物

参数	说明
--derivedDataDir DIR	构建输出根目录，默认 ~/DerivedData，每个工程在其中有自己的 <名字>-<哈希> 文件夹
--clean	构建前清空输出目录
-o, --ipa PATH	把 iOS 应用打包为 .ipa 放到 PATH。不写也会打包，默认在 <工程目录>\build\<App>.ipa，非 Release 配置是 <App>-<配置>.ipa
--no-ipa	Release 也不打包 .ipa
-i, --install	成功后把签好名的 App 安装到已连接的设备，等于接着执行 kxdevice install
--emit-commands-only	只生成 compile_commands.json 供编辑器代码提示，不编译、不链接、不签名

性能与诊断

参数	说明
-j, --jobs N	并行任务数，默认 CPU 核数
--explain	打印每个任务重新执行的原因，从未构建、命令变了、输出被改或输入重建
--timing	打印加载、规划、执行各阶段耗时
-v, --verbose	打印每条命令行
--no-cache	不使用缓存的构建计划，重新规划

Swift 包

build 会按需自动解析依赖。以下四个参数和 resolve 通用。

参数	说明
--only-use-versions-from-resolved-file	严格按 Package.resolved 中的版本解析，同 xcodebuild -onlyUsePackageVersionsFromResolvedFile
--skip-package-updates	解析时不访问远程仓库，同 -skipPackageUpdates
--disable-package-repository-cache	不使用共享的包仓库缓存，同 -disablePackageRepositoryCache
--package-cache-path DIR	共享包缓存目录，同 -packageCachePath

产物

.app 与中间文件在 ~/DerivedData/<名字>-<哈希>/Build/Products/<配置>-iphoneos/。
iOS 应用另外生成 <工程目录>\build\<App>.ipa（非 Release 配置是 <App>-<配置>.ipa），应用嵌了 Swift 库时会带上 App Store Connect 要求的 SwiftSupport/。Release 包旁边的 <App>.AppStoreInfo.plist 是 Transporter 上传时可选的资源描述文件。
--emit-commands-only 只写 <工程根>/compile_commands.json。
--json 时最后一条结果含 success、产物路径、ipa 路径和耗时。

例子

> kxbuild build .\MyApp.xcodeproj --install

> kxbuild build .\MyApp.xcworkspace -s MyApp -c Release --clean -D CODE_SIGN_IDENTITY="Apple Distribution"

> kxbuild build .\MyApp.xcodeproj --sdk iphonesimulator --arch arm64 -D CODE_SIGNING_ALLOWED=NO

> kxbuild build .\MyApp.xcodeproj --emit-commands-only

依次为 Debug 构建并安装到手机、Release 出 ipa 并临时指定 Distribution 证书、模拟器 SDK 只编译不签名、只给编辑器生成补全数据库。

脚本与 CI

以上命令在流水线中可以直接使用，成功退出码为 0，失败为非 0。典型的 CI 出包命令如下。

> kxbuild build MyApp.xcworkspace -s MyApp -c Release --clean --derivedDataDir .\out --skip-package-updates --ipa .\out\MyApp.ipa --json

参数	用途
--json	输出为每行一条的 JSON 事件，脚本按 success 和产物路径字段取结果。排错时不要加
--derivedDataDir DIR	构建输出固定到工作区内，每次从干净目录开始，方便收集产物
--skip-package-updates	Swift 包严格按 Package.resolved 的版本，不访问远程，保证可重复
--clean	不混入上次构建的中间产物

React Native、Expo、Flutter 的构建脚本调用 xcodebuild 和 xcrun 时会使用 KXBuild 的同名命令，脚本不需要修改，见 xcodebuild / xcrun 兼容。

resolve

kxbuild resolve <project.xcodeproj | project.xcworkspace | 包目录> [参数]

解析工程的 Swift Package 依赖，检出到 <DerivedData>/<名字>-<哈希>/SourcePackages/。build 会自动执行，单独运行用于预热缓存或重置损坏的依赖。

参数	说明
--force	先清空检出和缓存再解析，同 Xcode 的 Reset Package Caches
--derivedDataDir DIR	同 build
--only-use-versions-from-resolved-file 等四个	同 build 的 Swift 包参数

> kxbuild resolve .\MyApp.xcodeproj --force

project

查看、新建、编辑和转换 Xcode 工程，添加 Swift Package 依赖和 App 扩展。内置模板各生成什么、怎么加自己的模板见项目模板。

子命令	作用
info	以 JSON 输出 target、scheme、Bundle ID 和可执行文件路径
templates	列出可用的工程模板
create	用模板新建工程
settings dump / apply	读取或批量修改构建设置
add-setting	增加或修改一个构建设置
add-folder	给工程添加一个文件夹分组
add-resource	把资源文件加入 target，如 .xcstrings、.xcassets
add-package	给 target 添加 Swift Package 依赖
add-target	给工程添加扩展、App Clip、框架、静态库或资源包
spm2app	把可执行 target 是 App 的 Swift Package 转为能出 ipa 的 App 工程

project info

kxbuild project info <project.xcodeproj | project.xcworkspace> [参数]

以 JSON 输出工程的 target、scheme、Bundle ID 和可执行文件路径。

参数	说明
-c, --config NAME	按这个配置读取设置，默认和 build 一样
--src	附带每个 target 的源文件和头文件搜索路径
--derivedDataDir DIR	使 executablePath 与 build 的输出目录一致

> kxbuild project info .\MyApp.xcodeproj --src

project templates

kxbuild project templates

列出可用的工程模板，包括 id、名称、说明和需要的工具。id 用于 create 的 -t 参数。每个模板的内容见项目模板。

project create

kxbuild project create -t <模板 id> -n <名字> [-b <Bundle ID>] [-o <父目录>] [--force] [--no-script]

在 <父目录>/<名字> 新建工程。CocoaPods、Flutter、React Native、Expo 模板创建后会接着执行 pod install、flutter create 等初始化。

参数	说明
-t, --type ID	模板 id，见 templates 或项目模板，必填
-n, --name NAME	工程名，字母开头，只能包含字母、数字和下划线，同时是目录名，必填
-b, --bundle-id ID	Bundle ID，默认 com.example.<名字>
-o, --output DIR	父目录，默认当前目录
--force	允许创建在非空目录中
--no-script	只复制模板，不执行生成脚本

> kxbuild project create -t app_swiftui -n MyApp -b com.example.myapp -o D:\projects

Windows 上 React Native 和 Expo 模板的依赖目录很深，父目录用短路径如 D:\p，否则会超出 260 字符路径上限。

project settings dump / apply

kxbuild project settings dump <工程> [--project NAME] [--all] [--ops FILE] [--derivedDataDir DIR]

以 JSON 输出每个 target 和配置的原始设置、解析后的值以及设置的类型说明。--all 连未显式设置的也列出，工作区中有多个工程时用 --project 指定，--ops FILE 先在内存中套用改动再计算，用于预览，不写盘。

kxbuild project settings apply <工程> --ops FILE [--project NAME]

批量修改 project.pbxproj。FILE 是 JSON 数组，每项一个操作。op 为 set、remove 或 rename，owner 为 project 或 target 名，config 为配置名或 * 表示全部配置，value 为字符串或字符串数组，rename 用 newKey。工程设置编辑器保存时就是调用它。

[
  {"op": "set",    "owner": "MyApp",   "config": "*",       "key": "MARKETING_VERSION", "value": "1.2.0"},
  {"op": "set",    "owner": "project", "config": "Debug",   "key": "OTHER_LDFLAGS",     "value": ["$(inherited)", "-ObjC"]},
  {"op": "remove", "owner": "MyApp",   "config": "Release", "key": "ENABLE_BITCODE"}
]

> kxbuild project settings apply .\MyApp.xcodeproj --ops ops.json

project add-setting

kxbuild project add-setting -k KEY -v VALUE -P <project.xcodeproj> [-t TARGET] [-c CONFIG] [-a]

增加或修改一个构建设置，只改一项时比写 ops 文件省事。

参数	说明
-k, --key KEY	设置名，如 HEADER_SEARCH_PATHS
-v, --value VALUE	值，数组用逗号分隔并加 -a
-a, --array	把逗号分隔的值作为数组写入
-t, --target NAME	修改这个 target，不填修改工程级
-c, --config NAME	只修改这个配置，不填修改全部配置
-P, --project PATH	.xcodeproj 路径，必填

> kxbuild project add-setting -k IPHONEOS_DEPLOYMENT_TARGET -v 15.0 -t MyApp -P .\MyApp.xcodeproj

project add-resource

kxbuild project add-resource -f <文件> -P <project.xcodeproj> [-t TARGET]

把一个资源文件加入 target 的资源，例如新建的 Localizable.xcstrings、Assets.xcassets、.storyboard。文件本身要先建好。已经在工程里的会直接复用，放在 Xcode 16 文件夹（同步文件夹）里的文件不用添加。

参数	说明
-f, --file PATH	资源文件，绝对路径或相对于工程所在目录
-t, --target NAME	加入这个 target，不填加入第一个
-P, --project PATH	.xcodeproj 路径，必填

> kxbuild project add-resource -f MyApp\Localizable.xcstrings -t MyApp -P .\MyApp.xcodeproj

project add-folder

kxbuild project add-folder -f <文件夹名> -P <project.xcodeproj> [-p <父分组>]

给工程的分组树添加一个文件夹分组，-p 不填则挂在根下。

project add-package

kxbuild project add-package -P <project.xcodeproj> (--url URL [版本规则] | --path DIR) [--product P,…] [-t TARGET]

给 target 添加 Swift Package 依赖，相当于 Xcode 的 Add Package Dependencies。添加后立即解析并更新 Package.resolved，产品名不对或解析失败时工程保持原样。远程包不给版本规则时用最新版本，允许升级到下一个主版本之前，仓库没有版本 tag 时跟默认分支，需要联网。

参数	说明
-P, --project PATH	.xcodeproj 路径，必填
--url URL	远程包的 Git 地址
--path DIR	本地包目录，与 --url 二选一
--product P,…	要链接的库产品，逗号分隔。包里只有一个库产品时可省略，有多个时不填会列出可选产品
-t, --target NAME	链接产品的 target，默认第一个
--from VERSION	从这个版本起，到下一个主版本之前
--up-to-next-minor VERSION	从这个版本起，到下一个次版本之前
--exact VERSION	固定这一个版本
--range A..<B	版本范围，如 5.0.0..<6.0.0
--branch NAME	跟随分支
--revision SHA	固定到某个提交
--no-resolve	只改工程，不联网解析，下次构建时再解析。要写明 --product，远程包还要写版本规则

> kxbuild project add-package -P .\MyApp.xcodeproj --url https://github.com/Alamofire/Alamofire.git --from 5.9.0 --product Alamofire

> kxbuild project add-package -P .\MyApp.xcodeproj -t MyApp --path ..\MyKit

project add-target

kxbuild project add-target -P <project.xcodeproj> --type <类型> --name <名称> [--language swift|objc] [--host TARGET | --no-host] [--bundle-id ID] [--app-group ID]

给工程添加 target，如小组件等 App 扩展、App Clip、框架、静态库、资源包，相当于 Xcode 的 File → New → Target。源码建在工程所在目录下的同名文件夹里，新 target 随 App 一起构建和安装，App 有哪些构建配置它也有哪些。出错时工程保持原样。扩展和 App Clip 签名前要在 Apple 开发者后台为它的 Bundle ID 注册 App ID 并生成描述文件，用了 --app-group 还要给两个 App ID 开启 App Groups，命令输出中会列出来，见证书与签名。

参数	说明
-P, --project PATH	.xcodeproj 路径，必填
--type TYPE	target 类型，见下表，必填
--name NAME	target 名，同时是源码文件夹名，字母开头，只能包含字母、数字和下划线，必填
--language LANG	框架和静态库的语言，swift 或 objc，默认 swift
--host NAME	添加到哪个 App target，工程里只有一个 App 时可省略
--no-host	框架、静态库、资源包不添加到任何 App
--bundle-id ID	Bundle ID。扩展默认是 App 的 Bundle ID 加点和小写的名称，必须以 App 的 Bundle ID 加点开头
--app-group ID	App 和扩展或 App Clip 共用的 App Group，如 group.com.example.myapp，两边要共享数据时填写
--list	列出全部类型

类型	作用
framework	动态框架，链接并嵌入 App，可选 Swift 或 Objective-C
static-library	静态库，链接进 App，可选 Swift 或 Objective-C
bundle	资源包，复制到 App 里
app-clip	App Clip，嵌入 App，Bundle ID 为 App 的加 .Clip
widget	主屏幕和锁屏小组件
widget-live-activity	小组件加一个显示在锁屏和灵动岛的实时活动
notification-service	推送显示前修改内容、下载附件
notification-content	自定义通知展开后的界面
share	从分享面板接收文字、链接和图片
action	在分享面板里处理其他 App 的内容
imessage	「信息」App 里的 iMessage 扩展
keyboard	自定义键盘
photo-editing	在「照片」App 里编辑照片
quicklook-preview	在「文件」等 App 里预览自定义文件
thumbnail	生成自定义文件的缩略图
safari-web-extension	Safari 网页扩展
content-blocker	Safari 内容拦截器
broadcast-upload	录屏直播的上传扩展
broadcast-setup-ui	录屏直播开始前的设置界面
file-provider	在「文件」App 里提供你的云端文件，需要 App Group
credential-provider	为密码自动填充提供账号密码
call-directory	来电识别与拦截号码
message-filter	过滤陌生人发来的短信
network-extension	VPN 隧道（Packet Tunnel）
device-activity-monitor	屏幕使用时间的活动监控
shield-configuration	屏幕使用时间的遮挡页面样式
shield-action	屏幕使用时间遮挡页面上的按钮处理
background-download	App 安装和更新时由系统下载资源包，iOS 26 起

> kxbuild project add-target -P .\MyApp.xcodeproj --type widget --name MyAppWidget --app-group group.com.example.myapp

project spm2app

kxbuild project spm2app <包目录> [-n NAME] [-b ID] [--executable E] [-o DIR] [--force] [--no-resolve]

可执行 target 是 SwiftUI 或 UIKit App 的包，用这份代码新建一个 iOS App 工程，以本地包的方式引用包，之后用 build 构建这个工程即可出 ipa。工程默认建在 <包目录>\<App 名>\，和包一起提交到版本库。只有库的包不转换，请用 add-package 加进 App 工程。如果 App 用到的同包 target 没有 library 产品，会在 Package.swift 里加一行 .library，命令输出中会列出这处改动。完整流程见纯 Swift Package。

参数	说明
-n, --name NAME	App 名，默认为 App 可执行产品名
-b, --bundle-id ID	Bundle ID，默认 com.example.<App 名>
--executable E	包里有多个 App 可执行 target 时选一个
-o, --output DIR	父目录，工程建在 <DIR>\<App 名>，默认包目录
--force	允许创建在非空目录中
--no-resolve	生成后不解析依赖

> kxbuild project spm2app . -n MyApp -b com.example.myapp

update

kxbuild update [--check] [--no-doctor]

升级 kxbuild 到最新版，直接下载替换本地程序即可运行，升级后自动用新版运行一次 doctor。

参数	说明
--check	只检查是否有新版本，不安装
--no-doctor	升级后不运行 doctor

> kxbuild update --check

version

kxbuild version [--json]

打印版本信息，--json 时只输出一个 JSON 对象，供脚本判断版本。求助时附上它的输出。

接下来

kxdevice 命令参考

kxdevice 的全部子命令与参数，按设备与配对、安装与 App、启动与截图、调试与符号、日志与崩溃、文件与沙盒、抓包与定位、备份与诊断、网页界面分组。

目录与环境变量

安装目录 KXBUILD_HOME 里有什么，证书目录、共享目录，工程目录下会出现什么，用得上的环境变量。