Flutter - 搭建引擎调试环境（iOS）_flutter ios真机调试

---

前言

刚开始学Flutter开发时搭建过，没有记录。现在有需要时又忘了，果然好记性不如烂笔头。

注意，调试环境搭建会占用较大硬盘空间。粗略统计，Flutter引擎项目（包含依赖的第三方库）约20GB，host_debug_unopt构建编译后约16GB，ios_debug_xxx构建编译后约5GB。所以如果想搭建成功，至少需要准备41GB的剩余硬盘空间。

开发环境

• macOS: 13.3.1
• Flutter: 3.7.12
• Xcode: 14.3

安装依赖环境

1. python3

后续很多工具依赖python环境，如果执行python3命令失败，那么需要先安装python3。可以通过官网下载安装或brew命令安装：

brew install python
1

安装过程可能会遇到这样的问题：

Error: python@3.11: the bottle needs the Apple Command Line Tools to be installed.
  You can install them, if desired, with:
    xcode-select --install
1
2
3

执行xcode-select --install命令安装Xcode命令行工具解决。

2. depot_tools

depot_tools是Chromium的源码管理工具，后续获取源码和构建编译都需要用到。

安装流程：

1. 切换到想要存放的路径执行clone命令（需要代理）

git clone https://chromium.googlesource.com/chromium/tools/depot_tools.git
1

2. 配置环境变量

在~/.bashrc或~/.zshrc文件中加上：

export PATH=[存放的路径]/depot_tools:$PATH
1

参考文档：

• Getting dependencies
• depot_tools_tutorial

获取引擎项目

按Flutter的文档应先fork项目，不过那是针对贡献者的流程，如果你只是调试，可以跳过这一流程。

1. 创建engine空目录

切换到想要存放Flutter引擎源码的位置新建engine目录：

mkdir engine
1

2. 创建.gclient文件并配置

切换到engine目录下执行：

touch .gclient
1

配置.gclient文件：

solutions = [{
	"managed": False,
	"name": "src/flutter",
	"url": "git@github.com:<your_name_here>/engine.git",
	"custom_deps": {},
	"deps_file": "DEPS",
	"safesync_url": "",
}, ]
1
2
3
4
5
6
7
8

<your_name_here>请按需替换，如果没有fork引擎项目，可以替换为flutter，如果有fork，可以替换为自己的Github账户名。

如果想了解这些配置的作用，参考官方文档：gclient file。

3. 指定引擎版本

前面的配置获取的是最新的Flutter引擎源码，但是Flutter引擎的调试离不开Flutter框架，如果版本不匹配可能会遇到一些问题，所以最好指定Flutter引擎版本为当前Flutter框架所需要的版本。那么这个版本怎么指定呢？

Flutter引擎版本其实就是commit id，可以在Flutter SDK目录/bin/internal/engine.version文件中获得。例如我当前电脑的Flutter版本是3.7.12，engine.version文件位于/opt/homebrew/Caskroom/flutter/3.7.12/flutter/bin/internal/目录，引擎版本是：

1a65d409c7a1438a34d21b60bf30a6fd5db59314
1

既然Flutter引擎版本是commit id，那么就可以通过修改前面的配置指定版本。修改后：

solutions = [{
	"managed": False,
	"name": "src/flutter",
	"url": "git@github.com:<your_name_here>/engine.git@1a65d409c7a1438a34d21b60bf30a6fd5db59314",
	"custom_deps": {},
	"deps_file": "DEPS",
	"safesync_url": "",
}, ]
1
2
3
4
5
6
7
8

4. 同步引擎源码

在engine目录下执行（需要代理）：

gclient sync
1

项目有点大，大概需要下载10GB，其中很大一部分是在下载依赖的第三方库，后续编译也相当耗时。

同步成功后，engine目录下会有一个src目录，如果在这个路径下执行git log，会发现commit id好像有点不对：

commit 8747bce41d0dc6d9dc45c4d1b46d2100bb9ee688 (HEAD)
Author: Jenn Magder <magder@google.com>
Date:   Wed Nov 30 14:05:32 2022 -0800

    Sort macOS SDK paths to keep order stable between runs (#652)
...
1
2
3
4
5
6

别急，真正的引擎项目在src目录下的flutter目录。src目录中的项目是这个buildroot，用于搭建Flutter引擎的构建环境。

5. 切换引擎版本

如果后续需要切换其他版本，请按以下步骤操作：

1. 切换到engine/src/flutter目录路径下
2. 指定新版本的commit id

git reset --hard [commit id]
1

3. 同步新版本的引擎源码

gclient sync -D --with_branch_heads --with_tags
1

参考文档：

• Getting the source

搭建调试环境

1. 构建编译

注意，以下所有命令都在engine/src目录路径下运行。

1.1 生成构建所需文件

1.1.1 主机端

flutter/tools/gn --unoptimized
1

生成的文件存放于engine/src/out/host_debug_unopt目录。

1.1.2 iOS端

• 真机调试

flutter/tools/gn --ios --unoptimized
1

生成的文件存放于engine/src/out/ios_debug_unopt目录。

• 模拟器调试

flutter/tools/gn --ios --simulator --unoptimized
# 如果是M系列芯片电脑，建议加上--simulator-cpu=arm64参数，用于支持arm64架构的模拟器
flutter/tools/gn --ios --simulator --simulator-cpu=arm64 --unoptimized
1
2
3

生成的文件存放于engine/src/out/ios_debug_sim_unopt或engine/src/out/ios_debug_sim_unopt_arm64目录。

如果是M系列芯片电脑，没有加上--simulator-cpu=arm64参数，后续Xcode模拟器调试可能会遇到没有iOS设备可选择的情况：

解决方法：按这个步骤[Xcode菜单栏] -> [Product] -> [Destination] -> [Destination Architectures] -> [Show Both]操作，显示全部iOS模拟器。

以上只生成了Debug模式相关的文件用于后续调试，如果需要更多模式（Profile/Release等），可以参考文档Flutter’s modes或通过flutter/tools/gn -h命令了解更多用法。

1.2 完成构建编译

• 真机调试

ninja -C out/ios_debug_unopt && ninja -C out/host_debug_unopt
1

• 模拟器调试

ninja -C out/ios_debug_sim_unopt && ninja -C out/host_debug_unopt
# 如果前面使用了--simulator-cpu=arm64参数
ninja -C out/ios_debug_sim_unopt_arm64 && ninja -C out/host_debug_unopt
1
2
3

首次构建编译比较耗时，CPU会满载（电脑买来这么久一直没转过的风扇终于了有表现的机会