EasyApp

安装指南

如何在开发环境中设置 EasyApp。

先决条件

开始之前，请确保满足以下要求：

  • macOS: 15.0 Sequoia 或更高版本
  • Xcode: 16.4 或更高版本

提醒

Xcode16.1/16.2版本存在拉取SPM依赖失败的问题，即使是开启了TUN模式，也会存在这个问题，推荐按照Xcode16.4以上的版本

  • Apple 开发者账号: 需要有效的开发者账号
  • Github账号: 访问代码仓库配置各种服务
  • Git: 用于下载/克隆仓库
  • iPhone 设备: 用于真机测试/调试，内购测试必须要使用真机
  • 网络连接: 用于下载第三方依赖仓库

提醒

Xcode 16.4 存在模拟器WebKitbug。由于 EasyApp内置了 WebView功能，所以在 Xcode 16.4上模拟器运行App会导致程序奔溃，两个解决办法：

1: 暂时使用Xcode16.3版本开发；或者最新的 Xcode 26 也行。

2: 使用真机调试。真机在所有版本上都不存在这个问题。

2.1: 真机运行必须要登录你的 Apple ID，如下图所示: addAccount

如何注册 Apple 开发者账号

参考官方文档：Apple 开发者账号注册

首先，当您购买 EasyApp 后，您会收到一封邮件，我们会向您发送 EasyApp 的前后端代码库的访问邀请。您需要接受这些邀请才能有权限访问代码库。紧接着，您需要将代码库克隆到本地，并配置 Xcode 项目。

克隆仓库

推荐 Fork 仓库，然后 再将 Fork 的仓库 Clone 到本地。这样您 Clone 的仓库也是私有仓库，并且您还可以随时拉取主仓库来更新代码。

fork_repo

然后根据您的克隆仓库执行以下代码：

  • your-username 替换为您的 Github 用户名
  • your-project-name 替换为您的项目名称
git clone https://github.com/your-username/easyapp-swiftui.git your-project-name

您也可以直接 clone 代码库

  • your-project-name 替换为您的项目名称
git clone https://github.com/FastEasyApp/easyapp-swiftui your-project-name

cd your-project-name

git remote remove origin

您也可以直接下载 ZIP 文件 download_zip

您也可以直接使用 Xcode 打开项目（需要先安装 Xcode） open_with_xcode

配置 Xcode

一个好的网络环境是提升开发效率的必要条件

  • 这里针对中国大陆地区,安装SPM 依赖需要开启代理 TUN 模式才能正常请求。
  • 或者使用 Proxifier 工具开启代理，如何 使用Proxifier，请自行搜索。相比于 使用 Proxifier 工具的繁琐配置，这里强烈推荐开启代理的 TUN 模式。
  • 如何开启代理 TUN 模式，请自行搜索，
  • 推荐使用Clash Verge 工具开启代理。

还有另外一种办法：

1: 让Xcode使用系统自带的git:

defaults write com.apple.dt.Xcode IDEPackageSupportUseBuiltinSCM YES

2: 然后给 git 设置全局代理或者设置终端代理，Xcode 就会使用代理了。

git config --global http.https://github.com.proxy {yourproxy} && git config --global https.https://github.com.proxy {yourproxy}

yourproxy替换成你的代理， 一般为 http://127.0.0.1:7897 端口可能不一样。

3: 查看 git 代理

 git config --list --global
http.https://github.com.proxy=http://127.0.0.1:7897
https.https://github.com.proxy=http://127.0.0.1:7897

4: 设置完成之后，需要重新拉取依赖

有2中方法：

1: 关闭Xcode，再重新打开，会重新自动拉取依赖

2: 右键 Package Dependencies, 点击 Reset Package Caches，会自动重新拉取依赖

resetSPM

配置主App

1. 在 Xcode 中打开项目:

前往您克隆的代码库，双击 EasyAppSwiftUI.xcodeproj 文件，即可打开项目。

open_xcode_project

2. 选择开发团队（如下图所示）:

  • 在 Xcode 中，选择项目文件（步骤 1 和 2）
  • 前往 "Signing & Capabilities" （步骤 3）
  • 选择你的 Apple 开发者团队 （步骤 4）

如果您还未注册Apple开发者账户，请参考官方文档来注册。这是必须的，否则您无法进行后续的开发工作。

3. 更新 Bundle Identifier:

  • 更改 bundle identifier 以匹配你的开发者账户（步骤 5）
  • 示例: com.yourcompany.easyappswiftui

edit_project_name

提醒

务必更新您的 Bundle Identifier，每个 App 的 Bundle Identifier 都是唯一的，后续您需要使用这个 Bundle Identifier 来配置各种服务：Supabase、RevenueCat、Apple 登录等。 editBId

当您更新完 Bundle Identifier 之后，Xcode 会自动更新您的Profile 文件，并且同步到 Apple Developer 网站。

模板默认启用了桌面小组件、锁屏小组件、灵动岛功能，由于您修改了主 App 的 Bundle Identifier，所以您也需要修改 Widget 和 推送通知 的 Bundle Identifier 。

提醒

如果您暂时不需要小组件和通知功能，可以参考这篇文档删除相关配置和代码。删除完成之后，程序没有报错，您可以直接跳过这一步。然后运行App，接着执行后续重命名项目操作。

他们的关系如下：

当你的iOS应用包含以下任何组件时，Apple要求这些组件的Bundle ID必须以主应用的Bundle ID为前缀：

  • App Extensions（应用扩展，如Today Widget、Share Extension等）

  • WatchKit App（Apple Watch应用）

  • App Clips

  • 其他嵌入式框架和二进制文件

举例说明

正确的配置：

  • 主应用：com.example.myapp

  • 扩展：com.example.myapp.share-extension ✅

  • Widget：com.example.myapp.widget ✅

错误的配置：

  • 主应用：com.example.myapp

  • 扩展：com.example.share-extension ❌（缺少 myapp. 前缀）

  • Widget：com.anothercompany.widget ❌（完全不同的前缀）

清理并重新构建：

Xcode 菜单栏 -> Product → Clean Build Folder

或者快捷键： (Shift + Cmd + K)

重新编译项目

具体步骤如下：

配置Widget相关配置

  1. 修改 Widget 的 Bundle Identifier

edit-widget 格式必须按照主 App 的 Bundle Identifier + .widget 来修改，

示例：

  • 主应用：com.example.myapp

  • Widget：com.example.myapp.widget ✅

当您更新完 Widget 的 Bundle Identifier 之后，Xcode 会自动更新您的Profile 文件，并且同步到 Apple Developer 网站。

接下来修改 EasyAppWidgetControl文件的 kind，如下图所示，该值就是您刚才修改的 Widget 的 Bundle Identifier。 widget-kind

  1. 新增 App Group 标识符

桌面小组件跟主 App 之间共享数据，需要配置 App Group 标识符。他们之间通过 App Group 标识符来共享数据。我们来到主 App 这里： widget-app-groups

点击 + 按钮，输入您的 App Group 标识符，推荐格式：group. + widget的Bundle Identifier。 比如：group.com.yourcompany.easyappswiftui.widget。

您设置完您的 App Group 标识符之后，请取消选中模板自带的 App Group 标识符。如下图所示，因为您已经配置了您专属的 App Group 标识符，所以模板自带的 App Group 标识符就没有存在的必要了。

remove-app-groups

  1. 主 App 配置完成之后，我们来到 Widget 这里：

edit-widget-app-groups

widget 的 App Group 会自动拉取主 App 的 App Group 标识符。选中即可。如果没拉取到，可以点击旁边的刷新按钮，重新拉取。

配置推送相关配置

模板自带了推送功能。推送整体跟Widget类似，先配置Bundle Identifier，然后配置 App Group。

  1. 修改推送的 Bundle Identifier，如下图所示： noti-app-groups

格式必须按照主 App 的 Bundle Identifier + .EasyAppSwiftUINotificationServiceExtension 来修改，

示例：

  • 主应用：com.example.myapp

  • 推送：com.example.myapp.EasyAppSwiftUINotificationServiceExtension ✅

    1. 新增 App Group 标识符

同样的来到主 App 这里：

widget-app-groups

点击 +，输入您的 App Group 标识符，推荐格式：group. + 推送的Bundle Identifier。比如：group.com.yourcompany.easyappswiftui.EasyAppSwiftUINotificationServiceExtension。

您设置完您的 App Group 标识符之后，请取消选中模板自带的 App Group 标识符。如下图所示，因为您已经配置了您专属的 App Group 标识符，所以模板自带的 App Group 标识符就没有存在的必要了。

remove-app-groups

  1. 主 App 配置完成之后，我们来到推送这里：

edit-noti-app-groups

推送的 App Group 会自动拉取主 App 的 App Group 标识符。选中即可。如果没拉取到，可以点击旁边的刷新按钮，重新拉取。

运行 App

  • 执行 Command + R 运行 App。
  • 此时您应该会看到App 已经安装到桌面了。并且App 的名字已经修改为 EasyAppCopy。

desktop

  • 紧接着，您就会进入引导页。 恭喜您，您已经成功运行了 EasyApp 🎉🎉🎉🎉🎉

first_lanuch

重命名项目(此步骤可选)

  • 因为这里只是修改项目工程名字，并不是修改 App 的名字。如果您觉得无所谓，可以跳过此步骤。
  • 选中项目名称之后，再次点击 或者 回车键 即可进入编辑状态（如下图所示）

edit_project_name2

  • 拿本项目举例，我们修改为 EasyAppSwiftUI_Copy（如下图所示）， edit_project_name3

  • 修改完成之后，点击/回车键 即可完成修改，会弹窗提醒，点击重命名，一路继续即可。

edit_project_name4

  • 重命名之后，Xcode 会重新索引整个项目。 project_indexing

  • 如果我们重新打开项目，会重新请求所有的 SPM 依赖。 fetch_dependencies

5. 检验项目是否正常运行

  • 您拿到了项目之后, 或者如果您操作了步骤 4，建议您执行一遍 Command + B 来检验项目是否正常Build。
  • 如果一切正常，您会看到 Build Success 的提示。

build_success

提醒

  • 如果因依赖项错误导致项目构建失败，可能是 Xcode 在项目重命名时出现问题。请尝试以下操作：
  • 执行 Command + Shift + K 清理缓存
  • 执行 File > Packages > Reset Package Caches reset_package_caches
  • 等待 Xcode 完成依赖项下载处理
  • 若仍未解决，请尝试完全退出 Xcode 后重新启动并执行：
  • Command + Shift + K 清理缓存
  • File > Packages > Reset Package Caches
  • 如何途中弹出任何弹出，都请允许/信任
  • 如果依赖项错误仍然存在，可能是您的 Package.resolved 文件已损坏。请删除该文件并让 Xcode 重新生成。参阅此 Stack Overflow 问题
  • 一般情况下，不会出现这种情况。如果您真的遇到了，并且您已经尝试了上述所有方法还是没解决，请联系我们

提醒

如果在您改完项目名字之后，有可能会遇到找不到主 App 的情况，如下图所示： notfindMain

遇到这种情况，请按照以下步骤操作，按照从上到下箭头处操作即可：

edit-s

6. 修改App名字

  • 如果您以上步骤一切顺利，您就可以着手修改您的 App 名字了（如下图所示）。
  • 选中步骤 1，找到Display Name，修改为您的 App 名字（步骤 2）。比如我们将 App 名字修改为 EasyAppCopy。

edit_app_name

接下来需要配置您需要配置如何连接 Supabase 服务。

App端 链接 Supabase 服务

学习 App 端 如何连接 Supabase 后端服务

权限配置(此步骤可选)

模板为了演示相关功能，所以默认开启了一些权限，所有的权限可以在这里查看

delete-pre

如果您的 App 不需要某个权限，请点击箭头图标，即可删除对应权限。

提醒

Apple 审核时，如果您的 App 申请了某个权限，但是却没有使用该权限，有可能会被拒绝。请在上架前核验一遍。

Last updated on

如何注册Apple开发者账号

了解如何快速注册Apple开发者账号

App端 链接 Supabase 服务

了解 EasyAppSwiftUI 项目如何链接 Supabase 服务