⚡

ExpoBuild&Deploy(iOS) expo-build-deploy

Expo React Native 应用的构建与部署指南，涵盖 EAS Build 配置、iOS 应用签名、TestFlight 提交、App Store 提交以及空中更新等关键步骤。

移动开发 0 次安装 0 次浏览 更新于 3/3/2026

expo-build-deploy 描述：构建和部署 Expo React Native 应用到 iOS。当配置 EAS Build、提交到 TestFlight、App Store 部署、管理证书或解决构建问题时使用。

Expo Build & Deploy (iOS)

EAS Build 设置

初始配置

# 安装 EAS CLI
npm install -g eas-cli

# 登录 Expo 账户
eas login

# 在项目中初始化 EAS
eas build:configure

这会创建 eas.json：

{
  "cli": {
    "version": ">= 5.0.0"
  },
  "build": {
    "development": {
      "developmentClient": true,
      "distribution": "internal",
      "ios": {
        "simulator": true
      }
    },
    "preview": {
      "distribution": "internal"
    },
    "production": {}
  },
  "submit": {
    "production": {}
  }
}

app.json iOS 配置

{
  "expo": {
    "name": "MyApp",
    "slug": "myapp",
    "version": "1.0.0",
    "scheme": "myapp",
    "ios": {
      "bundleIdentifier": "com.yourcompany.myapp",
      "buildNumber": "1",
      "supportsTablet": false,
      "infoPlist": {
        "NSCameraUsageDescription": "Take photos for your profile",
        "NSLocationWhenInUseUsageDescription": "Find locations near you"
      }
    }
  }
}

构建类型

开发构建（用于开发）

# 针对模拟器
eas build --profile development --platform ios

# 针对物理设备
eas build --profile development --platform ios --local

与 npx expo start --dev-client 一起使用

预览构建（内部测试）

eas build --profile preview --platform ios

通过 ad-hoc 配置分发。测试者通过链接安装。

生产构建（App Store）

eas build --profile production --platform ios

凭证管理

EAS 自动管理凭证，但您可以控制它们：

# 查看当前凭证
eas credentials

# 让 EAS 管理一切（推荐）
# 只需运行构建，它处理证书

# 使用现有凭证
eas credentials --platform ios
# 选择 "Use existing" 并提供路径

手动凭证设置（如果需要）

  1. 在 Apple Developer Portal 中创建 App ID
  2. 创建分发证书
  3. 创建配置文件
  4. 在 eas.json 中配置：
{
  "build": {
    "production": {
      "ios": {
        "credentialsSource": "local"
      }
    }
  }
}

环境变量

在 eas.json 中

{
  "build": {
    "production": {
      "env": {
        "API_URL": "https://api.yourapp.com"
      }
    },
    "preview": {
      "env": {
        "API_URL": "https://staging-api.yourapp.com"
      }
    }
  }
}

密钥（敏感值）

# 设置密钥
eas secret:create --name API_KEY --value "sk_live_xxx" --scope project

# 列出密钥
eas secret:list

# 在 app.json 中使用
{
  "extra": {
    "apiKey": process.env.API_KEY
  }
}

在代码中访问：

import Constants from 'expo-constants';

const apiKey = Constants.expoConfig?.extra?.apiKey;

TestFlight 部署

配置提交配置文件

{
  "submit": {
    "production": {
      "ios": {
        "appleId": "your@email.com",
        "ascAppId": "1234567890",
        "appleTeamId": "XXXXXXXXXX"
      }
    }
  }
}

从 App Store Connect URL 获取 ascAppId：https://appstoreconnect.apple.com/apps/1234567890

提交到 TestFlight

# 构建并提交一个命令
eas build --profile production --platform ios --auto-submit

# 或提交现有构建
eas submit --platform ios --latest

# 提交特定构建
eas submit --platform ios --id <build-id>

App Store Connect 设置（首次）

  1. 在 App Store Connect 中创建应用
  2. 填写应用信息
  3. 设置 TestFlight：
    • 添加内部测试者（立即访问）
    • 创建外部测试组（需要审核）

App Store 提交

提交前检查清单

  • [ ] 应用图标（App Store 1024x1024）
  • [ ] 所需设备尺寸的截图
  • [ ] 隐私政策 URL
  • [ ] 应用描述和关键词
  • [ ] 年龄分级问卷
  • [ ] 出口合规（加密）

提交审核

  1. 使用生产配置文件构建
  2. 提交到 App Store Connect
  3. 在 App Store Connect 中：
    • 选择提交的构建
    • 完成应用信息
    • 提交审核
# 自动提交
eas submit --platform ios --latest

空中更新

对于 JS/资产更改（无原生代码更改）：

# 发布更新
eas update --branch production --message "Bug fix for login"

# 发布前预览
eas update --branch preview --message "Testing new feature"

配置更新通道

{
  "build": {
    "production": {
      "channel": "production"
    },
    "preview": {
      "channel": "preview"
    }
  }
}

在应用中检查更新

import * as Updates from 'expo-updates';

async function checkForUpdates() {
  if (__DEV__) return; // 开发中跳过
  
  try {
    const update = await Updates.checkForUpdateAsync();
    if (update.isAvailable) {
      await Updates.fetchUpdateAsync();
      await Updates.reloadAsync();
    }
  } catch (error) {
    console.log('Update check failed:', error);
  }
}

版本管理

为新功能增加版本

{
  "expo": {
    "version": "1.1.0"  // 显示给用户
  }
}

每次构建增加 buildNumber

{
  "expo": {
    "ios": {
      "buildNumber": "2"  // 每次上传必须增加
    }
  }
}

使用 EAS 自动化

{
  "build": {
    "production": {
      "ios": {
        "autoIncrement": "buildNumber"
      }
    }
  }
}

本地构建

在您的机器上而不是 EAS 服务器上构建：

# 需要安装 Xcode
eas build --platform ios --local

适用于：

  • 调试期间快速迭代
  • 检查构建输出
  • 离线构建

故障排除

构建失败，签名错误

# 重置凭证，让 EAS 重新生成
eas credentials --platform ios
# 选择 "Remove" 然后重新构建

“Missing compliance” 警告

添加到 app.json：

{
  "expo": {
    "ios": {
      "infoPlist": {
        "ITSAppUsesNonExemptEncryption": false
      }
    }
  }
}

构建成功但应用崩溃

# 检查原生日志
eas build:view <build-id>

# 下载并检查构建
eas build:download <build-id>

TestFlight 构建处理中卡住

  • 通常需要 10-30 分钟
  • 在 App Store Connect 中检查状态
  • 确保 buildNumber 是唯一的

OTA 更新未应用

  • 验证通道匹配
  • 检查 Updates.checkForUpdateAsync() 是否被调用
  • 确保不在开发模式
  • 更新仅在下一次冷启动时应用

常用命令参考

# 构建
eas build --platform ios --profile production
eas build --platform ios --profile preview
eas build --platform ios --local

# 提交
eas submit --platform ios --latest
eas submit --platform ios --id <build-id>

# 更新
eas update --branch production --message "Fix"

eas update:list

# 凭证
eas credentials --platform ios
eas credentials:configure

# 查看构建
eas build:list
eas build:view <build-id>
eas build:cancel <build-id>

# 密钥
eas secret:create --name KEY --value "xxx"
eas secret:list