iblai-ios

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

/iblai-ios

Build and run your ibl.ai app on iOS using Tauri v2. Covers project initialization, Simulator development, real device testing, and production .ipa builds.

使用Tauri v2在iOS上构建并运行你的ibl.ai应用。内容涵盖项目初始化、模拟器开发、真机测试和生产环境.ipa包构建。

Prerequisites

前置条件

macOS (iOS builds require Xcode)
Xcode installed from the Mac App Store (includes iOS SDK + Simulator)
Xcode Command Line Tools:
```
xcode-select --install
```

Rust toolchain with iOS targets:

bash

rustup target add aarch64-apple-ios aarch64-apple-ios-sim

Tauri support already added to your project:
bash
```
iblai add builds
pnpm install
```

macOS（iOS构建需要Xcode）
Xcode 从Mac App Store安装（包含iOS SDK + 模拟器）
Xcode命令行工具:
```
xcode-select --install
```

Rust工具链 带iOS目标：

bash

rustup target add aarch64-apple-ios aarch64-apple-ios-sim

你的项目已添加Tauri支持：
bash
```
iblai add builds
pnpm install
```

Step 1: Initialize the iOS Project

步骤1：初始化iOS项目

Run this once after adding Tauri support:

bash

iblai builds ios init

This generates

src-tauri/gen/apple/

with the Xcode project, Swift bridge code, and iOS configuration. You only need to run this once.

If you get a Rust target error, make sure both targets are installed:
rustup target add aarch64-apple-ios aarch64-apple-ios-sim

添加Tauri支持后只需运行一次以下命令：

bash

iblai builds ios init

这会生成

src-tauri/gen/apple/

目录，内含Xcode项目、Swift桥接代码和iOS配置，你只需执行一次本命令。

如果你遇到Rust目标错误，请确保两个目标都已安装：
rustup target add aarch64-apple-ios aarch64-apple-ios-sim

Step 2: Run on iOS Simulator

步骤2：在iOS模拟器上运行

bash

iblai builds ios dev

Or use the pnpm script:

bash

pnpm tauri:dev:ios

This:

Starts the Next.js dev server
Compiles the Rust backend for the iOS Simulator target (
```
aarch64-apple-ios-sim
```
)
Launches the app in the default iOS Simulator

The first build takes several minutes (Rust compilation). Subsequent builds are fast thanks to incremental compilation.

bash

iblai builds ios dev

或者使用pnpm脚本：

bash

pnpm tauri:dev:ios

该命令会执行以下操作：

启动Next.js开发服务器
为iOS模拟器目标（
```
aarch64-apple-ios-sim
```
）编译Rust后端
在默认iOS模拟器中启动应用

首次构建需要数分钟（Rust编译耗时），后续增量编译速度会快很多。

Choosing a Specific Simulator

选择指定模拟器

List available simulators:

bash

iblai builds device

Then specify one:

bash

iblai builds ios dev --device "iPhone 16 Pro"

列出可用模拟器：

bash

iblai builds device

然后指定目标设备运行：

bash

iblai builds ios dev --device "iPhone 16 Pro"

Troubleshooting Simulator

模拟器故障排查

"No available iOS simulators": Open Xcode > Settings > Platforms > download an iOS runtime
Build fails with "linking" errors: Verify Xcode path with
```
xcode-select -p
```
. If incorrect, the user should run
```
sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
```
themselves (requires elevated privileges -- confirm with the user before suggesting this)
Simulator won't launch: Try
```
xcrun simctl shutdown all
```
then retry

"无可用iOS模拟器"：打开Xcode > 设置 > 平台 > 下载对应iOS运行时
构建报"链接"错误：用
```
xcode-select -p
```
验证Xcode路径，如果路径错误，用户需自行运行
```
sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
```
（需要管理员权限——建议前请先和用户确认）
模拟器无法启动：尝试运行
```
xcrun simctl shutdown all
```
后重试

Step 3: Run on a Physical Device

步骤3：在物理真机上运行

Connect your iPhone via USB, then:

bash

iblai builds ios dev --device

This deploys to the connected device instead of the Simulator.

通过USB连接你的iPhone，然后运行：

bash

iblai builds ios dev --device

该命令会将应用部署到连接的真机而非模拟器。

Requirements for Physical Devices

真机运行要求

Apple Developer account (free or paid)
Device registered in your Apple Developer portal
Development provisioning profile configured in Xcode

To set up signing:

Open
```
src-tauri/gen/apple/<app>.xcodeproj
```
in Xcode
Select the target > Signing & Capabilities
Set your Team and Bundle Identifier
Xcode auto-manages provisioning profiles

Free developer accounts can run on up to 3 devices for 7 days. A paid Apple Developer Program ($99/year) removes this restriction.

Apple开发者账号（免费或付费）
设备已在Apple开发者门户注册
Xcode中已配置开发Provisioning Profile

签名设置步骤：

在Xcode中打开
```
src-tauri/gen/apple/<app>.xcodeproj
```
选择目标 > 签名与能力（Signing & Capabilities）
设置你的团队和Bundle ID
Xcode会自动管理Provisioning Profile

免费开发者账号最多可在3台设备上运行应用，有效期7天。付费Apple开发者计划（99美元/年）可解除该限制。

Step 4: Build a Release .ipa

步骤4：构建发布版.ipa

Local Build (Ad Hoc / Development)

本地构建（Ad Hoc / 开发版）

bash

iblai builds ios build

Or:

bash

pnpm tauri:build:ios

The .ipa file is generated at

src-tauri/gen/apple/build/

(or use

find src-tauri/gen/apple -name "*.ipa"

to locate it).

bash

iblai builds ios build

或者：

bash

pnpm tauri:build:ios

生成的.ipa文件存放在

src-tauri/gen/apple/build/

目录下（也可以运行

find src-tauri/gen/apple -name "*.ipa"

定位文件）。

App Store Build (CI)

App Store构建（CI）

Generate the GitHub Actions workflow:

bash

iblai builds ci-workflow --ios

This creates

.github/workflows/tauri-build-ios.yml

which:

Sets up Node.js, pnpm, and Rust with iOS targets
Installs the Tauri CLI

Runs

cargo tauri ios init

and

cargo tauri ios build --export-method app-store-connect

Uploads the .ipa as a build artifact

生成GitHub Actions工作流：

bash

iblai builds ci-workflow --ios

这会创建

.github/workflows/tauri-build-ios.yml

文件，该工作流会执行以下操作：

配置Node.js、pnpm和带iOS目标的Rust环境
安装Tauri CLI

运行

cargo tauri ios init

和

cargo tauri ios build --export-method app-store-connect

上传.ipa作为构建产物

Required GitHub Secrets for CI

CI需要的GitHub Secrets

Secret	Description
`APPLE_API_KEY_BASE64`	Base64-encoded App Store Connect API key (.p8 file)
`APPLE_API_KEY_ID`	Key ID from App Store Connect > Users and Access > Keys
`APPLE_API_ISSUER`	Issuer ID from App Store Connect > Users and Access > Keys

To encode your .p8 key:

bash

base64 -i AuthKey_XXXXXXXXXX.p8 | pbcopy

密钥	描述
`APPLE_API_KEY_BASE64`	Base64编码的App Store Connect API密钥（.p8文件）
`APPLE_API_KEY_ID`	App Store Connect > 用户与访问 > 密钥页面获取的密钥ID
`APPLE_API_ISSUER`	App Store Connect > 用户与访问 > 密钥页面获取的Issuer ID

编码你的.p8密钥：

bash

base64 -i AuthKey_XXXXXXXXXX.p8 | pbcopy

App Icons

应用图标

Generate iOS-ready icons from your logo:

bash

iblai builds iconography path/to/logo.png

This creates all required sizes in

src-tauri/icons/

. Tauri maps them to the iOS asset catalog during

ios init

从你的logo生成适配iOS的图标：

bash

iblai builds iconography path/to/logo.png

这会在

src-tauri/icons/

目录下生成所有所需尺寸的图标，Tauri会在执行

ios init

时将它们映射到iOS资产目录中。

Summary of Commands

命令汇总

Task	Command
Add Tauri support	`iblai add builds`
Initialize iOS project	`iblai builds ios init`
Run on Simulator	`iblai builds ios dev`
Run on physical device	`iblai builds ios dev --device`
List available devices	`iblai builds device`
Build release .ipa	`iblai builds ios build`
Generate CI workflow	`iblai builds ci-workflow --ios`
Generate app icons	`iblai builds iconography logo.png`

任务	命令
添加Tauri支持	`iblai add builds`
初始化iOS项目	`iblai builds ios init`
在模拟器运行	`iblai builds ios dev`
在物理真机运行	`iblai builds ios dev --device`
列出可用设备	`iblai builds device`
构建发布版.ipa	`iblai builds ios build`
生成CI工作流	`iblai builds ci-workflow --ios`
生成应用图标	`iblai builds iconography logo.png`

Reference

参考

iblai-app-cli -- CLI source and templates
```
iblai builds --help
```
-- full list of build commands

iblai-app-cli -- CLI源码和模板
```
iblai builds --help
```
-- 完整构建命令列表