expo-dev-client

在本地或通过 TestFlight 构建和分发 Expo 开发客户端

Use EAS Build to create development clients for testing native code changes on physical devices. Use this for creating custom Expo Go clients for testing branches of your app.

## Important: When Development Clients Are Needed

**Only create development clients when your app requires custom native code.** Most apps work fine in Expo Go.

You need a dev client ONLY when using:
- Local Expo modules (custom native code)
- Apple targets (widgets, app clips, extensions)
- Third-party native modules not in Expo Go

**Try Expo Go first** with `npx expo start`. If everything works, you don't need a dev client.

## EAS Configuration

Ensure `eas.json` has a development profile:

```json
{
  "cli": {
    "version": ">= 16.0.1",
    "appVersionSource": "remote"
  },
  "build": {
    "production": {
      "autoIncrement": true
    },
    "development": {
      "autoIncrement": true,
      "developmentClient": true
    }
  },
  "submit": {
    "production": {},
    "development": {}
  }
}
```

Key settings:
- `developmentClient: true` - Bundles expo-dev-client for development builds
- `autoIncrement: true` - Automatically increments build numbers
- `appVersionSource: "remote"` - Uses EAS as the source of truth for version numbers

## Building for TestFlight

Build iOS dev client and submit to TestFlight in one command:

```bash
eas build -p ios --profile development --submit
```

This will:
1. Build the development client in the cloud
2. Automatically submit to App Store Connect
3. Send you an email when the build is ready in TestFlight

After receiving the TestFlight email:
1. Download the build from TestFlight on your device
2. Launch the app to see the expo-dev-client UI
3. Connect to your local Metro bundler or scan a QR code

## Building Locally

Build a development client on your machine:

```bash
# iOS (requires Xcode)
eas build -p ios --profile development --local

# Android
eas build -p android --profile development --local
```

Local builds output:
- iOS: `.ipa` file
- Android: `.apk` or `.aab` file

## Installing Local Builds

Install iOS build on simulator:

```bash
# Find the .app in the .tar.gz output
tar -xzf build-*.tar.gz
xcrun simctl install booted ./path/to/App.app
```

Install iOS build on device (requires signing):

```bash
# Use Xcode Devices window or ideviceinstaller
ideviceinstaller -i build.ipa
```

Install Android build:

```bash
adb install build.apk
```

## Building for Specific Platform

```bash
# iOS only
eas build -p ios --profile development

# Android only
eas build -p android --profile development

# Both platforms
eas build --profile development
```

## Checking Build Status

```bash
# List recent builds
eas build:list

# View build details
eas build:view
```

## Using the Dev Client

Once installed, the dev client provides:
- **Development server connection** - Enter your Metro bundler URL or scan QR
- **Build information** - View native build details
- **Launcher UI** - Switch between development servers

Connect to local development:

```bash
# Start Metro bundler
npx expo start --dev-client

# Scan QR code with dev client or enter URL manually
```

## Troubleshooting

**Build fails with signing errors:**
```bash
eas credentials
```

**Clear build cache:**
```bash
eas build -p ios --profile development --clear-cache
```

**Check EAS CLI version:**
```bash
eas --version
eas update
```

---

## 中文说明

使用 EAS Build 创建开发客户端，以便在物理设备上测试原生代码改动。当你需要为测试应用的某个分支而创建自定义 Expo Go 客户端时，请使用此功能。

## 重要：何时需要开发客户端

**仅在你的应用需要自定义原生代码时才创建开发客户端。** 大多数应用在 Expo Go 中都能正常运行。

只有在使用以下内容时你才需要开发客户端：
- 本地 Expo 模块（自定义原生代码）
- Apple targets（小组件、app clips、扩展）
- Expo Go 中不包含的第三方原生模块

**先尝试 Expo Go**，使用 `npx expo start`。如果一切正常，你就不需要开发客户端。

## EAS 配置

确保 `eas.json` 中包含一个开发配置档：

```json
{
  "cli": {
    "version": ">= 16.0.1",
    "appVersionSource": "remote"
  },
  "build": {
    "production": {
      "autoIncrement": true
    },
    "development": {
      "autoIncrement": true,
      "developmentClient": true
    }
  },
  "submit": {
    "production": {},
    "development": {}
  }
}
```

关键设置：
- `developmentClient: true` - 为开发构建打包 expo-dev-client
- `autoIncrement: true` - 自动递增构建号
- `appVersionSource: "remote"` - 以 EAS 作为版本号的唯一可信来源

## 为 TestFlight 构建

用一条命令构建 iOS 开发客户端并提交到 TestFlight：

```bash
eas build -p ios --profile development --submit
```

它将会：
1. 在云端构建开发客户端
2. 自动提交到 App Store Connect
3. 当构建在 TestFlight 中就绪时给你发送一封邮件

收到 TestFlight 邮件后：
1. 在你的设备上从 TestFlight 下载该构建
2. 启动应用以查看 expo-dev-client 界面
3. 连接到你本地的 Metro bundler 或扫描二维码

## 本地构建

在你的机器上构建开发客户端：

```bash
# iOS (requires Xcode)
eas build -p ios --profile development --local

# Android
eas build -p android --profile development --local
```

本地构建输出：
- iOS：`.ipa` 文件
- Android：`.apk` 或 `.aab` 文件

## 安装本地构建

在模拟器上安装 iOS 构建：

```bash
# Find the .app in the .tar.gz output
tar -xzf build-*.tar.gz
xcrun simctl install booted ./path/to/App.app
```

在设备上安装 iOS 构建（需要签名）：

```bash
# Use Xcode Devices window or ideviceinstaller
ideviceinstaller -i build.ipa
```

安装 Android 构建：

```bash
adb install build.apk
```

## 为特定平台构建

```bash
# iOS only
eas build -p ios --profile development

# Android only
eas build -p android --profile development

# Both platforms
eas build --profile development
```

## 检查构建状态

```bash
# List recent builds
eas build:list

# View build details
eas build:view
```

## 使用开发客户端

安装完成后，开发客户端会提供：
- **开发服务器连接** - 输入你的 Metro bundler URL 或扫描二维码
- **构建信息** - 查看原生构建详情
- **启动器界面** - 在多个开发服务器之间切换

连接到本地开发环境：

```bash
# Start Metro bundler
npx expo start --dev-client

# Scan QR code with dev client or enter URL manually
```

## 故障排查

**构建因签名错误失败：**
```bash
eas credentials
```

**清除构建缓存：**
```bash
eas build -p ios --profile development --clear-cache
```

**检查 EAS CLI 版本：**
```bash
eas --version
eas update
```