项目模板
新建项目时可选的 11 个内置模板，模板目录的结构，以及如何添加自定义模板。VS Code 向导和命令行使用同一份模板。
内置模板
共 11 个，按向导中的顺序排列。id 用于命令行 kxbuild project create -t。所有模板的部署目标为 iOS 15，不包含签名材料，证书按证书与签名配置。
原生应用
| 模板 | id | 内容 |
|---|---|---|
| iOS 应用（SwiftUI） | app_swiftui | App 入口和 ContentView，无 Storyboard |
| iOS 应用（Swift · UIKit） | app_swift | 单页 UIKit 应用，Storyboard、SceneDelegate、资源目录 |
| iOS 应用（WKWebView 套壳 / H5） | app_webview | 整个界面是一个 WKWebView，加载打包的 www/ 目录或远程 URL，带进度条、返回手势和 JS 与原生互调示例 |
| iOS 应用（Objective-C · UIKit） | app_objc | Objective-C 单页 UIKit 应用，Storyboard、资源目录 |
| iOS 应用（Objective-C + Swift 混编） | app_objc_swift | Objective-C 主体加 Swift 文件，桥接头和 -Swift.h 双向调用示例 |
| iOS 应用（Swift · CocoaPods） | app_swift_cocoapods | Swift UIKit 应用加 Podfile，创建后自动执行 pod install |
跨平台应用
这三个模板通过各框架的脚手架生成工程，再由 kxbuild doctor 完成 iOS 端配置，需要几分钟。
| 模板 | id | 内容 | 需要 |
|---|---|---|---|
| Flutter 应用 | flutter_app | flutter create 生成的 iOS 和 Android 工程，Bundle ID 写入 Runner target | Flutter SDK |
| React Native 应用 | react_native_app | React Native 社区 CLI 初始化，完成 pod install | Node.js、CocoaPods，随工具链安装 |
| Expo 应用 | expo_app | create-expo-app 初始化，执行 expo prebuild 和 pod install | Node.js、CocoaPods，随工具链安装 |
库
| 模板 | id | 内容 |
|---|---|---|
| Framework（Swift 动态库） | framework_swift | iOS 动态 Framework，带伞头文件和一个 public 示例类 |
| 静态库（Objective-C） | lib_static_objc | lib<Name>.a，公开头文件输出到 include/<Name>/ |
模板结构
一个模板就是一个目录，目录名即模板 id。除 template.json 和 template.sh 外，其余文件原样复制到新工程中。
app_swift/
template.json 名字、说明、排序、依赖
template.sh 可选，复制完成后在新工程目录中执行
.gitignore
__NAME__.xcodeproj/
__NAME__/
AppDelegate.swift …文件内容和文件名中的占位符都会被替换，二进制文件原样复制。
| 占位符 | 替换为 |
|---|---|
| __NAME__ | 项目名 |
| __BUNDLE_ID__ | Bundle ID |
| __DATE__ | 创建日期，格式 yyyy/MM/dd |
template.json 示例
{
"name": { "en": "iOS App (Swift, UIKit)", "zh": "iOS 应用（Swift · UIKit）" },
"description": { "en": "…", "zh": "…" },
"category": "app", // app | library | hybrid
"order": 10, // 列表中的位置，小的在前
"requires": ["cocoapods"] // 可选，依赖的外部工具，向导中标注在名字后面
}template.sh 在复制和占位符替换之后用 bash 执行，Windows 上使用工具链自带的 MSYS2 bash，工作目录为新工程目录。脚本可以读取以下环境变量。
| 变量 | 值 |
|---|---|
| KXBUILD_PROJECT_NAME / KXBUILD_BUNDLE_ID | 项目名、Bundle ID |
| KXBUILD_PROJECT_DIR | 新工程目录 |
| KXBUILD_TEMPLATE_ID / KXBUILD_TEMPLATE_DIR | 模板 id、模板目录 |
| KXBUILD_HOME / KXBUILD_BIN | 工具链目录、kxbuild 可执行文件 |
脚本退出码非 0 视为创建失败，工程目录保留。模板可以不带任何文件，只用 template.sh 生成整个工程，Flutter、React Native、Expo 三个内置模板就是这样。Windows 上调用原生工具要用 pod.bat、npx.cmd、flutter.bat 这样的名字。
自定义模板
把常用的工程结构做成模板，新建项目时直接选用。
| 步骤 | 说明 |
|---|---|
| 1 准备工程 | 用最接近的内置模板新建一个工程，改成需要的样子并编译通过。删除 build/、xcuserdata/ 等产物，不要包含证书 |
| 2 替换占位符 | 工程名出现的地方全部换成 __NAME__，包括 .xcodeproj 目录名、源码目录名、pbxproj 中的 target 和产品名、Info.plist。Bundle ID 换成 __BUNDLE_ID__ |
| 3 添加 template.json | 目录名作为 id，不要和内置模板重名，例如 mycorp_app |
| 4 放入模板目录 | 整个目录复制到 KXBUILD_HOME\resources\templates\，重新打开新建向导即可看到 |
也可以不带文件，只写一个 template.sh，用现有脚手架或 git clone 生成工程。工具链更新只覆盖同名目录，自定义模板会保留，因此 id 不能和内置模板重名。模板可以复制到其他机器的同一位置使用。