iblai-build

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

/iblai-build

Build and run your ibl.ai app on desktop and mobile using Tauri v2. Covers iOS, Android, macOS/Linux desktop, and Surface tablet builds.

Before adding build support or running a dev build, stop all running dev servers (

pnpm dev

next dev

, etc.) to avoid port conflicts. Kill any process on port 3000 before proceeding.

When the user asks to add iOS or Android build support, automatically start the emulator/simulator after initialization -- just like you would start

pnpm dev

after adding auth. Run

iblai builds device

to find the available device name, then start the dev build with that device.

Do NOT guess device names. Always run

iblai builds device

first and use a device name from the output.

使用 Tauri v2 在桌面端和移动端构建并运行你的 ibl.ai 应用，覆盖 iOS、Android、macOS/Linux 桌面端以及 Surface 平板的构建需求。

在添加构建支持或运行开发构建之前，请停止所有正在运行的开发服务器（

pnpm dev

、

next dev

等）以避免端口冲突。继续操作前请终止占用3000端口的所有进程。

当用户要求添加iOS或Android构建支持时，初始化完成后请自动启动模拟器——就像你添加认证功能后会启动

pnpm dev

一样。运行

iblai builds device

查询可用设备名称，然后使用该设备名称启动开发构建。

请勿猜测设备名称，请务必先运行

iblai builds device

，并使用输出结果中的设备名称。

Prerequisites (All Platforms)

前置要求（所有平台）

Tauri support added to your project:
bash
```
iblai add builds
pnpm install
```
Rust toolchain installed via rustup

你的项目已添加Tauri支持：
bash
```
iblai add builds
pnpm install
```
已通过rustup安装Rust工具链

How Dev Builds Work

开发构建工作原理

All platforms (desktop and mobile) use a static

next build

export. The CLI runs the frontend build automatically before starting the Tauri dev server -- there is no separate

devUrl

beforeDevCommand

. The Tauri WebView loads the static files from

../out

on all platforms.

所有平台（桌面端和移动端）都使用静态

next build

导出产物。CLI在启动Tauri开发服务器前会自动运行前端构建——无需单独配置

devUrl

或

beforeDevCommand

。所有平台的Tauri WebView都会从

../out

目录加载静态文件。

Mobile Safe Area

移动端安全区域

The generated CSS includes

padding: env(safe-area-inset-*)

<body>

and the layout sets

viewport-fit=cover

. This prevents content from overlapping with the iOS status bar / notch and Android status bar. If you see content behind the status bar, verify:

globals.css

(or

iblai-styles.css

) has

padding-top: env(safe-area-inset-top)

on body

app/layout.tsx

metadata includes

viewport: "width=device-width, initial-scale=1, viewport-fit=cover"

生成的CSS在

<body>

标签上包含

padding: env(safe-area-inset-*)

配置，布局也设置了

viewport-fit=cover

。这可以避免内容与iOS状态栏/刘海屏、Android状态栏重叠。如果你发现状态栏遮挡了内容，请检查：

globals.css

（或

iblai-styles.css

）中body标签是否配置了

padding-top: env(safe-area-inset-top)

app/layout.tsx

的元数据中是否包含

viewport: "width=device-width, initial-scale=1, viewport-fit=cover"

App Icons

应用图标

Generate platform-ready icons from your logo (works for all platforms):

bash

iblai builds iconography path/to/logo.png

This creates all required sizes in

src-tauri/icons/

从你的logo生成适配所有平台的图标（全平台通用）：

bash

iblai builds iconography path/to/logo.png

该命令会在

src-tauri/icons/

目录下生成所有需要的尺寸的图标文件。

List Available Devices

列出可用设备

bash

iblai builds device

bash

iblai builds device

iOS

Build and run on iOS Simulator and real devices.

在iOS模拟器和真机上构建并运行应用。

iOS Prerequisites

iOS前置要求

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

Rust iOS targets:

bash

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

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

Rust iOS目标平台：

bash

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

Initialize iOS Project

初始化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.

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

Run on iOS Simulator

在iOS模拟器上运行

First, find available simulators:

bash

iblai builds device

Then start the dev build with a device from the output:

bash

iblai builds ios dev --device "<device name from iblai builds device>"

Or without specifying a device (uses the default simulator):

bash

iblai builds ios dev

This starts the Next.js dev server, compiles Rust for

aarch64-apple-ios-sim

, and launches the app in the iOS Simulator. The first build takes several minutes; subsequent builds are fast.

首先查询可用模拟器：

bash

iblai builds device

然后使用输出中的设备名称启动开发构建：

bash

iblai builds ios dev --device "<device name from iblai builds device>"

也可以不指定设备（使用默认模拟器）：

bash

iblai builds ios dev

该命令会启动Next.js开发服务器，为

aarch64-apple-ios-sim

编译Rust代码，然后在iOS模拟器中启动应用。首次构建需要几分钟时间，后续构建速度会很快。

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
```
后重试

Run on Physical iOS Device

在iOS真机上运行

Connect your iPhone via USB, then:

bash

iblai builds ios dev --device

通过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中已配置开发配置文件

设置签名的步骤：

在Xcode中打开
```
src-tauri/gen/apple/<app>.xcodeproj
```
选择目标 > 签名与能力
设置你的团队和包标识符
Xcode会自动管理配置文件

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

Build Release .ipa

构建发布版.ipa

Local Build

本地构建

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 the full pipeline and uploads the .ipa as a build artifact.

生成GitHub Actions工作流：

bash

iblai builds ci-workflow --ios

该命令会创建

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

文件，配置完整的构建流水线，并将.ipa作为构建产物上传。

Required GitHub Secrets for iOS CI

iOS 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 > 用户和访问 > 密钥页面获取的发行方ID

编码.p8密钥的方法：

bash

base64 -i AuthKey_XXXXXXXXXX.p8 | pbcopy

Android

Build and run on Android emulators and real devices.

在Android模拟器和真机上构建并运行应用。

Android Prerequisites

Android前置要求

Android Studio with SDK and NDK installed
Android SDK (API level 24+)

Rust Android targets:

bash

rustup target add aarch64-linux-android armv7-linux-androideabi i686-linux-android x86_64-linux-android

已安装Android Studio，并配置好SDK和NDK
Android SDK（API等级24+）

Rust Android目标平台：

bash

rustup target add aarch64-linux-android armv7-linux-androideabi i686-linux-android x86_64-linux-android

Initialize Android Project

初始化Android项目

bash

iblai builds android init

This generates

src-tauri/gen/android/

with the Gradle project.

bash

iblai builds android init

该命令会生成

src-tauri/gen/android/

目录，包含Gradle项目。

Run on Android Emulator

在Android模拟器上运行

First, find available emulators:

bash

iblai builds device

Then start the dev build:

bash

iblai builds android dev

Or:

bash

pnpm tauri:dev:android

首先查询可用模拟器：

bash

iblai builds device

然后启动开发构建：

bash

iblai builds android dev

或者：

bash

pnpm tauri:dev:android

Run on Physical Android Device

在Android真机上运行

Connect your device via USB with USB debugging enabled, then:

bash

iblai builds android dev --device

开启USB调试后通过USB连接设备，然后运行：

bash

iblai builds android dev --device

Build Release APK

构建发布版APK

bash

iblai builds android build

Or:

bash

pnpm tauri:build:android

bash

iblai builds android build

或者：

bash

pnpm tauri:build:android

Android CI

bash

iblai builds ci-workflow --android

bash

iblai builds ci-workflow --android

macOS (Desktop)

macOS（桌面端）

macOS Prerequisites

macOS前置要求

Xcode Command Line Tools:
```
xcode-select --install
```

Xcode命令行工具：
```
xcode-select --install
```

Run in Dev Mode

开发模式运行

bash

iblai builds dev

Or:

bash

pnpm tauri:dev

bash

iblai builds dev

或者：

bash

pnpm tauri:dev

Build Release .dmg / .app

构建发布版.dmg / .app

bash

iblai builds build

Or:

bash

pnpm tauri:build

bash

iblai builds build

或者：

bash

pnpm tauri:build

macOS CI

bash

iblai builds ci-workflow --mac

bash

iblai builds ci-workflow --mac

Surface

Build for Microsoft Surface tablets running Windows.

为运行Windows系统的微软Surface平板构建应用。

Surface Prerequisites

Surface前置要求

Visual Studio Build Tools with C++ workload
WebView2 runtime (included on Windows 11, downloadable for Windows 10)

已安装带C++ workload的Visual Studio构建工具
WebView2运行时（Windows 11已预装，Windows 10可单独下载）

Run in Dev Mode

开发模式运行

bash

iblai builds dev

bash

iblai builds dev

Build Release .msi / .exe

构建发布版.msi / .exe

bash

iblai builds build

The installer targets are configured in

src-tauri/tauri.conf.json

under

bundle.targets

(includes

nsis

and

msi

by default).

bash

iblai builds build

安装包目标配置在

src-tauri/tauri.conf.json

的

bundle.targets

下（默认包含

nsis

和

msi

）。

Surface CI

bash

iblai builds ci-workflow --windows

bash

iblai builds ci-workflow --windows

Linux (Desktop)

Linux（桌面端）

Linux Prerequisites

Linux前置要求

System dependencies (Debian/Ubuntu):

bash

sudo apt install libwebkit2gtk-4.1-dev build-essential libssl-dev libgtk-3-dev libayatana-appindicator3-dev librsvg2-dev

系统依赖（Debian/Ubuntu）：

bash

sudo apt install libwebkit2gtk-4.1-dev build-essential libssl-dev libgtk-3-dev libayatana-appindicator3-dev librsvg2-dev

Run in Dev Mode

开发模式运行

bash

iblai builds dev

bash

iblai builds dev

Build Release .deb / .AppImage

构建发布版.deb / .AppImage

bash

iblai builds build

bash

iblai builds build

Linux CI

bash

iblai builds ci-workflow --linux

bash

iblai builds ci-workflow --linux

All Platforms CI

全平台CI

Generate CI workflows for all platforms at once:

bash

iblai builds ci-workflow --all

一次性生成所有平台的CI工作流：

bash

iblai builds ci-workflow --all

Summary of Commands

命令汇总

Task	Command
Add Tauri support	`iblai add builds`
Generate app icons	`iblai builds iconography logo.png`
List available devices	`iblai builds device`
iOS
Initialize iOS project	`iblai builds ios init`
Run on iOS Simulator	`iblai builds ios dev`
Run on specific simulator	`iblai builds ios dev --device "<name>"`
Run on physical iPhone	`iblai builds ios dev --device`
Build release .ipa	`iblai builds ios build`
iOS CI workflow	`iblai builds ci-workflow --ios`
Android
Initialize Android project	`iblai builds android init`
Run on Android emulator	`iblai builds android dev`
Run on physical Android	`iblai builds android dev --device`
Build release APK	`iblai builds android build`
Android CI workflow	`iblai builds ci-workflow --android`
Desktop
Run desktop dev mode	`iblai builds dev`
Build desktop release	`iblai builds build`
macOS CI workflow	`iblai builds ci-workflow --mac`
Surface CI workflow	`iblai builds ci-workflow --windows`
Linux CI workflow	`iblai builds ci-workflow --linux`
All CI workflows	`iblai builds ci-workflow --all`

任务	命令
添加Tauri支持	`iblai add builds`
生成应用图标	`iblai builds iconography logo.png`
列出可用设备	`iblai builds device`
iOS
初始化iOS项目	`iblai builds ios init`
在iOS模拟器上运行	`iblai builds ios dev`
在指定模拟器上运行	`iblai builds ios dev --device "<name>"`
在iPhone真机上运行	`iblai builds ios dev --device`
构建发布版.ipa	`iblai builds ios build`
iOS CI工作流	`iblai builds ci-workflow --ios`
Android
初始化Android项目	`iblai builds android init`
在Android模拟器上运行	`iblai builds android dev`
在Android真机上运行	`iblai builds android dev --device`
构建发布版APK	`iblai builds android build`
Android CI工作流	`iblai builds ci-workflow --android`
桌面端
运行桌面端开发模式	`iblai builds dev`
构建桌面端发布版	`iblai builds build`
macOS CI工作流	`iblai builds ci-workflow --mac`
Surface CI工作流	`iblai builds ci-workflow --windows`
Linux CI工作流	`iblai builds ci-workflow --linux`
全平台CI工作流	`iblai builds ci-workflow --all`

Reference

参考

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

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