教程目录

Godot 4 导出 iOS 怎么装到 iPhone？Windows 上调试 Godot iOS 工程

Q: 重新导出后我改过的 Info.plist 没了，怎么办？

重新导出会整体重新生成 MyGame.xcodeproj 和 MyGame 文件夹，手动改动都会被覆盖。把要保留的 Info.plist 键写进导出预设的 Additional Plist Content，权限说明写进 Privacy 分组，这样每次导出都会带上。

最后更新 2026-10-23

Godot 4 导出 iOS 只生成 Xcode 工程，不会生成 ipa，要装到 iPhone 还得编译、签名和安装。做法是在同一台 Windows 电脑上，把 Godot 导出的工程用 KXBuild 编译，按 F5 装到 iPhone 上调试，最后打出上架用的 Release ipa。Godot 中照常导出，导出目录按普通 Xcode 工程使用，不用改 Godot 项目设置。

你需要 Apple 开发者账号、一台 iPhone 和数据线，并且已经安装 KXBuild。文中的 Godot 字段名以官方文档为准，截至 2026 年 10 月，Godot 最新稳定版是 4.7.2。

Godot 导出 iOS 到装机的整体流程是什么？

Godot 负责游戏本身和导出，KXBuild 负责之后的步骤。两边的分工如下。

步骤	在哪里做	产物
开发场景和 GDScript	Godot 编辑器	Godot 项目
下载导出模板、填 iOS 导出预设	Godot 编辑器	导出预设
导出	Godot 编辑器	`MyGame.xcodeproj` 等文件
体检、签名、编译、安装、调试	VS Code + KXBuild	装在 iPhone 上的游戏
Release 构建	VS Code 或命令行	`MyGame.ipa`

下文以项目名 MyGame、Bundle ID com.example.mygame、导出目录 D:\g\mygame-ios 为例。

第 1 步：Godot 版本要求是什么？

这篇按 Godot 4.x 写，4.7.x 的字段和界面与文中一致。Godot 3.x 的 iOS 导出选项不同，不适用。

在 Godot 编辑器菜单「帮助 → 关于 Godot」里能看到版本号。导出模板必须和编辑器版本完全一致，升级编辑器后要重新下载一次模板。

项目用 C# 写的，Godot 文档把 C# 的 iOS 导出标为实验性，有不少限制，下文按 GDScript 项目讲。

第 2 步：怎么下载导出模板？

导出模板是 Godot 预先编译好的 iOS 版引擎，导出时会拷进 Xcode 工程。

在 Godot 编辑器菜单「编辑器 → 管理导出模板」打开模板管理窗口。
点「下载并安装」，下载源保持默认即可。
下载完成后窗口顶部显示当前版本已安装。

网络不好下载失败时，可以在 Godot 官网下载页手动下载同版本的 .tpz 文件，再在同一窗口点「从文件安装」选择它。

第 3 步：iOS 导出预设怎么填？

菜单「项目 → 导出」，点「添加…」，选 iOS。右侧会列出这个预设的全部选项，按分组填写。Godot 用中文界面时选项名会翻译成中文，下表给出英文原名，方便对照官方文档。

Application 分组

选项	填什么
App Store Team ID	开发者账号的 Team ID，10 位字符，在开发者网站 Membership details 里查看，必填
Bundle Identifier	和开发者后台注册的 App ID 一致，如 `com.example.mygame`，只能用字母、数字、连字符和点，必填
Min iOS Version	最低支持的系统版本，默认 14.0
Short Version	商店显示的版本号，如 `1.0.0`，留空用项目版本
Version	构建号，每次上传 App Store Connect 都要比上一次大，留空用项目版本
Export Project Only	勾选后只导出 Xcode 工程，在 Windows 上建议勾选
Code Sign Identity（Debug / Release）	留空。留空时 Debug 用 Apple Development，Release 用 Apple Distribution
Provisioning Profile UUID / Specifier	留空。留空时工程是自动签名，KXBuild 按 Bundle ID 匹配描述文件

App Store Team ID 或 Bundle Identifier 没填，导出窗口会显示错误，无法导出。Team ID 要填 10 位的代码，不是团队名称。填错了构建时会因为团队对不上而找不到证书。

描述文件 UUID 一旦填了，导出的工程会改成手动签名，只认这一份描述文件，换手机或续期后容易对不上，所以保持留空。

最低系统版本怎么定，可以参考最低支持 iOS 版本怎么定。

Icons 分组

最重要的是 App Store 1024×1024 和 Icon 1024×1024 两项，其他尺寸留空时 Godot 会用项目图标生成。上架用的 1024 图标不能透明，也不能带 alpha 通道，否则上传时报 ITMS-90717，见 ITMS 错误码。

图标、启动屏的通用要求见上架前把图标、启动屏和多语言一次做好。启动屏在 Storyboard 分组设置，可以选图片缩放方式和背景色。

Privacy 分组

游戏用到下面的能力，就要在这里填用途说明，内容会写进导出工程的 Info.plist。

选项	对应的 Info.plist 键	什么时候必填
Camera Usage Description	NSCameraUsageDescription	用到摄像头
Microphone Usage Description	NSMicrophoneUsageDescription	用到麦克风
Photo Library Usage Description	NSPhotoLibraryUsageDescription	读写相册

用到了却没填，游戏调用时会直接闪退，审核也会被拒。写法见 Info.plist 权限用途说明。每项还有对应的本地化版本，可以分别填中文和英文。

同一分组里还有隐私清单相关的选项，比如文件时间戳、磁盘空间、开机时间等必需原因 API 的理由，以及是否追踪用户、收集了哪些数据。按游戏和第三方插件的实际情况勾选，规则见 iOS 隐私清单 PrivacyInfo.xcprivacy 怎么写。

其他分组

Capabilities。Performance A12 会把可安装的设备限制在 iPhone XS、XR 及更新机型，Performance Gaming Tier 限制在 iPhone 15 Pro 及更新机型。不确定就不勾，勾了以后老设备在 App Store 上看不到这款游戏。
Plugins。项目的 ios/plugins 里有 iOS 插件时，这里会列出它们，要用的逐个勾选，不勾选的不会打进工程。
Additional Plist Content（在 Application 分组）。要额外加的 Info.plist 键写在这里，格式是 <key> 加值的 XML 片段。以后重新导出也会保留，比改导出后的文件可靠。

第 4 步：为什么要导出到空目录？

在导出窗口底部点「导出项目…」，按下面的方式选位置。

新建一个 Godot 项目以外的空目录，例如 D:\g\mygame-ios。不要放在 Godot 项目目录里面，否则 Godot 会把导出产物当成项目资源导入。
文件名填 MyGame.ipa。文件名决定 Xcode 工程和 target 的名字，不要带空格。
「Export With Debug」先保持勾选，开发阶段用调试版引擎，出错时信息更完整。
点「保存」。

没有勾选 Export Project Only 时，导出结束会出现一条警告，说 .ipa 只能在 macOS 上生成，Xcode 工程保持不变。这是正常现象，导出目录里已经有了需要的文件。

导出完成后，目录里大致是这些内容。

文件	作用
`MyGame.xcodeproj`	Xcode 工程，KXBuild 打开的就是它
`MyGame\`	Info.plist、entitlements、图标、启动屏等工程文件
`MyGame.pck`	打包好的场景、资源和 GDScript
`.xcframework` 文件	导出模板里的引擎库，以及勾选的插件库

路径尽量短，像 D:\g\mygame-ios 这样。引擎库层级很深，放得太深在 Windows 上容易遇到路径过长的错误。

第 5 步：在 VS Code 中打开并体检

在 VS Code 中「文件 → 打开文件夹」打开导出目录 D:\g\mygame-ios，KXBuild 视图会列出 MyGame 工程和同名的 target。

第一次打开先体检，它会检查编译需要的环境并修好缺的部分。以下两种做法任选其一。

VS Code 插件。在 KXBuild 视图标题栏「···」中运行「体检并修复开发环境」。
命令行。在导出目录执行下面的命令。

1kxbuild doctor .\MyGame.xcodeproj

导出目录里的原生代码（插件的 Objective-C、Swift）在 VS Code 中有补全和跳转，用法见代码提示与索引。GDScript 和场景照常在 Godot 中编辑。

第 6 步：签名证书放在哪里？

开发阶段要两样东西。Apple Development 证书（.p12），和包含这部 iPhone UDID、Bundle ID 为 com.example.mygame 的 Development 描述文件（.mobileprovision）。还没有的，按在 Windows 上申请 iOS 开发证书、描述文件和 p12准备。

证书目录可以放两个位置。

导出目录下的 keychain\，例如 D:\g\mygame-ios\keychain\，只对这个工程生效。重新导出时 Godot 只清理 MyGame.xcodeproj 和 MyGame\ 两个文件夹，放在导出目录根下的 keychain\ 不受影响。
%USERPROFILE%\kxbuild\keychain\，所有工程共用，换导出目录也不用再拷。

目录里放 .p12、.mobileprovision 和 password.properties，后者每行写一张证书的「文件名=密码」。

1keychain\
2├─ development.p12
3├─ MyGame_Dev.mobileprovision
4└─ password.properties

放好之后构建时会按工程中的签名设置自动签名，不用在 KXBuild 里配置。详细规则见证书与签名。

第 7 步：按 F5 装到 iPhone 上运行

用数据线连上 iPhone，解锁后点「信任此电脑」，并在「设置 → 隐私与安全性 → 开发者模式」中打开开发者模式，手机会重启一次。驱动和手机设置见设备准备。

确认 KXBuild 视图「构建配置」节点是 Debug，选中这台 iPhone，按 F5。KXBuild 会依次构建、签名、安装、启动游戏并附加调试器。第一次调试某个 iOS 版本时会自动下载对应的符号库，有几个 GB，只需一次。

只想重新装一次、不重新编译时，用 KXBuild 视图标题栏的「运行」，它会直接安装上一次的构建产物并启动。三种启动方式的区别见运行与调试。

原生层断点和 GDScript 怎么调试？

两种代码各用各的调试器，互不影响。

代码	在哪里调试	怎么做
插件的 Objective-C、Swift、C++	VS Code	在源码里下断点，按 F5，单步、变量、调用栈都是标准调试视图
GDScript 和场景	Godot 编辑器	在 Godot 里下断点、运行场景，用 Godot 自己的调试器
真机上的 GDScript 输出	VS Code「输出 → KXBuild Console」	在 GDScript 里用 `print()` 打印

游戏在真机上运行时，Godot 引擎的日志和 GDScript 的 print()、push_error() 输出都会写进系统日志，显示在 VS Code「输出」面板的 KXBuild Console 通道，构建日志在 KXBuild 通道。输出面板用 Ctrl+Shift+U 打开，右上角下拉框切换。

只在 iPhone 上出现的问题，例如触控、权限弹窗、内存不足，先在 GDScript 里加 print() 缩小范围。闪退时 VS Code 会停在崩溃位置，调用栈里能看到是引擎、插件还是系统框架里出的错。日志的更多看法见 iOS 真机日志怎么看。

改完游戏之后要重新导出吗？

改了 GDScript、场景或资源，在 Godot 中重新导出到同一个目录、同样的文件名，回到 VS Code 按 F5。

重新导出时，Godot 会清空并重新生成下面两处，你在里面做的手动修改都会丢失。

位置	包含	会不会被覆盖
`MyGame.xcodeproj`	工程文件、构建设置、签名设置	会，整个重新生成
`MyGame\`	Info.plist、entitlements、图标、启动屏	会，整个重新生成
`MyGame.pck`	场景、资源、脚本	会，换成新导出的
导出目录根下的 `keychain\`、`.vscode\` 等	证书、VS Code 设置	不会

所以要长期保留的改动，都放回 Godot 的导出预设里。

额外的 Info.plist 键写进 Additional Plist Content。
权限说明写进 Privacy 分组。
版本号、构建号写进 Short Version 和 Version。
设备能力写进 Capabilities。

临时试一下的改动，可以直接用属性列表编辑器改 MyGame\MyGame-Info.plist，或者用工程设置编辑器改构建设置，记住下次导出会被冲掉。

另外不要往 MyGame\ 文件夹里放自己的文件。Godot 重新导出前会检查这个文件夹，发现太多它不认识的文件时会报 Unexpected files found 并停止导出，这时把那些文件挪走，或者换一个空目录导出。

怎么打出上架用的 Release ipa？

出包前在 Godot 里重新导出一次，这次有两处不同。

确认 Version 比上一次上传的大，Short Version 是要发布的版本号。
导出时取消勾选「Export With Debug」。导出的工程只带一份引擎库，勾选时带的是调试版，出包前要换成发布版。

证书目录里还要有 Apple Distribution 证书和 App Store 类型的描述文件。导出预设的 Release 签名身份留空时就是 Apple Distribution，不用再改工程。

然后以下两种做法任选其一。

VS Code 插件。在命令面板或工程的右键菜单运行 KXBuild: 生成 App Store ipa。
命令行。在导出目录执行下面的命令。

1kxbuild build .\MyGame.xcodeproj -c Release --export app-store

构建完成后导出目录的 build 文件夹下会生成 MyGame.ipa。在 Windows 上用 Appuploader 上传到 App Store Connect，处理完成后先在 TestFlight 发给测试员验证，再提交审核。完整流程见发布与上架和在 Windows 上上架 App Store。

Godot 导出 iOS 常见报错怎么解决？

现象	原因	处理
导出窗口提示找不到导出模板	没装模板，或者模板和编辑器版本不一致	「编辑器 → 管理导出模板」下载当前版本的模板
提示 App Store Team ID not specified	Team ID 没填	在 Application 分组填 10 位 Team ID
提示 Invalid Identifier	Bundle ID 含下划线、空格等字符	只用字母、数字、连字符和点
导出结束提示 .ipa can only be built on macOS	在 Windows 上 Godot 不生成 ipa	正常现象，用导出的 Xcode 工程继续；勾选 Export Project Only 后不再提示
提示 Unexpected files found in the export destination directory	导出目录里有 Godot 不认识的文件	把自己放进去的文件挪走，或者换一个空目录
提示 Metal renderer require iOS 14+	Min iOS Version 低于 14	Forward+ 和 Mobile 渲染器在 iOS 上用 Metal，最低版本改回 14.0 及以上
编译时报插件的头文件或符号找不到	插件没有 iOS 版本，或者没在 Plugins 分组勾选	确认插件提供 iOS 库，在导出预设里勾选后重新导出
GDExtension 在 iPhone 上没加载	`.gdextension` 文件里没有 iOS 平台的库	给 `[libraries]` 加上 ios 条目，并提供 iOS 版本的库文件
一调用相机或麦克风就闪退	没填权限用途说明	在 Privacy 分组填写后重新导出
签名报找不到描述文件	证书目录里没有这个 Bundle ID 的描述文件，或者不含这台手机	按证书与签名补齐，签名报错对照 16 条常见错误

渲染器的选择在 Godot 项目设置的 Rendering 分组。Compatibility 渲染器在 iOS 上走 OpenGL ES 3，Forward+ 和 Mobile 走 Metal。Godot 导出 iOS 后画面异常或启动时黑屏，先换成另一个渲染器导出一次，确认是不是渲染相关的问题。

常见问题

Godot 在 Windows 上能直接导出 iOS 的 ipa 吗？

不能。Godot 在 Windows 上只生成 Xcode 工程，导出结束会提示 .ipa 只能在 macOS 上生成。在 Windows 上用 KXBuild 打开这个工程，选 Release 构建就能得到 ipa。

重新导出后我改过的 Info.plist 没了，怎么办？

重新导出会整体重新生成 MyGame.xcodeproj 和 MyGame 文件夹，手动改动都会被覆盖。把要保留的 Info.plist 键写进导出预设的 Additional Plist Content，权限说明写进 Privacy 分组，这样每次导出都会带上。

GDScript 能在 VS Code 里打断点吗？

GDScript 用 Godot 自己的调试器，在 Godot 编辑器里下断点。VS Code 里调试的是导出工程中的原生代码，真机上 GDScript 的 print() 输出可以在 KXBuild Console 里看到。

导出时 Bundle Identifier 和 Team ID 填哪里的值？

Team ID 是开发者网站 Membership details 里的 10 位代码，不是团队名称。Bundle Identifier 要和开发者后台注册的 App ID、描述文件里的完全一致，例如 com.example.mygame。

上架包为什么要取消 Export With Debug？

导出的工程只带一份引擎库，勾选 Export With Debug 时带的是调试版，体积更大、运行更慢。出 Release ipa 前取消勾选重新导出，再用 Release 配置构建。