排错与 FAQ
先跑 kxbuild doctor；然后按错误消息查安装、工程、签名、设备、发布、插件六类问题，以及日志在哪看。
先运行体检
大多数安装、编译、连接问题都是环境问题。先运行 kxbuild doctor 检查并修复工具链、SDK、CocoaPods、Node 和设备驱动，带上工程路径还会按工程类型准备 Flutter、React Native、Expo、Kotlin Multiplatform 所需的环境。VS Code 中运行 KXBuild: 体检并修复开发环境。
> kxbuild doctor> kxbuild doctor D:\projects\MyApp -v-v 输出每一步和子进程的完整日志，求助时附上这份输出最有用。升级 kxbuild 用 kxbuild update，升级后自动再体检一次。排错时不要加 --json，错误说明在普通输出中。
日志位置
| 内容 | 位置 |
|---|---|
| 构建日志 | VS Code「输出」面板的 KXBuild 通道，命令行在终端。加 -v 查看每条编译命令 |
| 编译错误 | VS Code「问题」面板，点一下跳到源码行 |
| 调试器输出 | 「调试控制台」 |
| 手机上的日志 | kxdevice syslog 查看系统日志，kxdevice ostrace 查看 os_log |
| 崩溃报告 | kxdevice crash |
| 体检详情 | kxbuild doctor -v |
按错误消息查
安装与工具链
- kxbuild: command not found / 不是内部或外部命令
- 原因安装脚本修改了 PATH，当前终端或 VS Code 是安装之前打开的。
- 处理新开终端，重启 VS Code。仍不行检查安装目录下的 bin 是否在 PATH 中，插件里可以点 KXBuild 视图的「选择已有的安装目录」指定。
- Swift 工具链下载中断
- 原因网络不稳定，工具链约 1 GB。
- 处理重新执行同一条安装命令，会断点续传。
- doctor 报 Swift SDK 和工具链版本不一致
- 原因手动换过工具链或 SDK。
- 处理让 doctor 修复，仍不一致则 kxbuild update 后再运行一次。
- Windows 上路径相关的错误（文件名过长、找不到文件）
- 原因没开长路径支持，或工程放得太深。
- 处理doctor 会开启系统的长路径支持，需要一次管理员授权。工程放到短路径如 D:\proj，React Native 和 Unity 导出的工程尤其要注意。
- 插件提示工具链版本不匹配 / 请运行 Doctor
- 原因插件和 kxbuild 只升级了一个。
- 处理按提示运行体检，或 kxbuild update 后重启 VS Code。
工程与编译
- 编译时报路径无效
- 原因给 kxbuild build 传了目录而不是工程文件。
- 处理路径以 .xcodeproj 或 .xcworkspace 结尾，Swift Package 传含 Package.swift 的目录。
- 编译报找不到依赖（Pods）
- 原因构建的是 .xcodeproj，而依赖在 CocoaPods 的工作区中。
- 处理先 pod install，再构建生成的 .xcworkspace。React Native、Flutter、Cordova 工程都是如此。
- 拉不到 Swift Package，或编译报找不到包
- 原因依赖还没解析，或缓存损坏。
- 处理kxbuild resolve <工程>，仍不行加 --force 重置缓存。
- Debug 构建链接时报 undefined symbol: …vpfi
- 原因开源 Swift 编译器按文件编译时的已知问题。@State private var count = 0 这类带初始值的属性，所在结构体的 init 写在另一个文件里就会出现。远程 Swift Package 默认已经整模块编译，报错的是工程自己的代码或本地包。
- 处理设置环境变量 KXBUILD_SWIFT_WHOLE_MODULE=all，重开终端或 VS Code 后再构建，所有 Swift 目标都改为整模块编译。只临时试一次可以加 -D KXBUILD_SWIFT_WHOLE_MODULE=all。也可以把 init 移到声明属性的文件里。
- Metal shaders (.metal) … need metal, which is not installed on this host
- 原因工程里有 Metal 着色器，本机没装 Apple 的 Metal 编译器。
- 处理登录 Apple 账号下载安装 Metal Developer Tools for Windows，见Metal 着色器。
- scheme / target "…" not found
- 原因名字不对，或 scheme 未共享。
- 处理kxbuild project info <工程> 列出全部 scheme 和 target。Unity 导出的 target 叫 Unity-iPhone。
- 新建工程时没有模板可选
- 原因模板组件还没安装。
- 处理再运行一次 kxbuild doctor。
- Run Script 阶段报错（Flutter / RN / KMP）
- 原因框架自己的工具没准备好，例如 Flutter SDK 没设 FLUTTER_ROOT、Node 依赖没安装、Kotlin/Native 没打补丁、JAVA_HOME 没设置。
- 处理带工程路径运行 kxbuild doctor <工程目录>，它会补齐这些环境。
- 代码提示不工作 / 跳转失效
- 原因compile_commands.json 过期，或 Swift 与 clangd 处理了同一种文件。
- 处理依次运行「KXBuild: 生成 compile_commands.json」和「KXBuild: 重启代码提示」，仍不行运行「KXBuild: 重建项目索引」。.m .mm .c .cpp 由 clangd 负责，Swift 由 SourceKit-LSP 负责，不要在设置中把 C 系语言加回 SourceKit-LSP。
签名
- No signing certificate matching "…" found
- 原因证书目录中没有工程要求的证书类型或团队不对。
- 处理放入对应的 .p12，或用 -D CODE_SIGN_IDENTITY=… -D DEVELOPMENT_TEAM=… 改成目录中已有的。
- no provisioning profile named "…"
- 原因工程指定了 PROVISIONING_PROFILE_SPECIFIER，目录中没有同名描述文件。
- 处理放入同名的 .mobileprovision，或把工程改回自动签名，按 Bundle ID 和团队自动匹配。
- 证书读不出来 / 口令错误
- 原因password.properties 中没有这张证书，或文件名不一致。
- 处理每行一张证书，格式为 文件名.p12=密码，文件名含后缀、区分大小写，密码中的等号或空格照写，不加引号。
- 编译成功，装到手机失败或装上打不开
- 原因没有签名，或描述文件中没有这部手机的 UDID，或企业证书没在手机上信任。
- 处理检查证书目录位置，见证书与签名。把 UDID 加进 Development 描述文件重新下载。企业签名在手机「设置 → 通用 → VPN 与设备管理」中信任。
设备与调试
- kxdevice device list 是空的
- 原因Apple 设备驱动或服务没启动，用的不是数据线，手机没解锁或没信任。
- 处理运行「KXBuild: 设备诊断」或 kxdevice doctor，换线换口，解锁手机点信任。「Apple 设备」能看到手机，KXBuild 就能看到。
- WSL 里看不到设备
- 原因没经过 Windows 侧中转，或手机被 usbipd 直通到了 WSL。
- 处理在 WSL 中运行 kxdevice doctor，不要同时用 usbipd 直通。
- 连不上 instruments / debugserver，或提示开发者模式
- 原因开发者模式没打开，或开发者镜像没挂载。
- 处理手机「设置 → 隐私与安全性 → 开发者模式」打开并重启，重新插拔后再按 F5。
- 断点不停 / 停在汇编上
- 原因用 Release 配置构建，优化后断点位置对不上，或符号库还没下载完。
- 处理调试用 Debug 配置，等待符号库下载完成。
- App 装上了但一打开就红屏（RN / Expo）
- 原因手机连不上电脑上的 Metro 开发服务器，是网络问题。
- 处理手机和电脑在同一网络，Windows 防火墙放行 Metro 端口，见 React Native 页。
- Dart 断点打不上（Flutter）
- 原因没安装 Dart 扩展。
- 处理安装 Dart-Code.dart-code 后重新调试。
发布
- Release 构建没有 .ipa
- 原因构建的不是应用 target，或加了 --no-ipa。
- 处理用 -s 指定应用的 scheme。
- 上传时报 Invalid Bundle / 缺少 SwiftSupport
- 原因上传的是手工打包的 zip，不是构建生成的 .ipa。
- 处理直接上传 build\<App>.ipa，它已包含 App Store Connect 要求的结构。
插件
- KXBuild 视图提示「本机没有找到 KXBuild 工具链」
- 原因还没安装工具链，或安装在插件找不到的位置。
- 处理点视图中的「安装 KXBuild」或「选择已有的安装目录」，安装后重载窗口。详见 安装插件与工具链。
- 插件提示版本不一致 / 请运行体检
- 原因插件和 kxbuild 只升级了一个。
- 处理运行「KXBuild: 体检并修复开发环境」，或在终端执行 kxbuild update。插件本身在扩展视图中更新。
- 工程设置编辑器变成只读，提示更新
- 原因kxbuild 版本过旧。
- 处理kxbuild update，仍只读则更新插件到最新版。
还没解决
把 kxbuild version、kxbuild doctor -v 的输出和出错命令的完整日志一起发到联系我们。能提供工程最好，不方便的话说明工程类型和 iOS 版本。