醋醋百科网

Good Luck To You!

2025年06月21日

Expo SDK 53.0.7 的 超详细 app.json 和 eas.json 配置项说明

以下是针对 Expo SDK 53.0.7 的 超详细 app.json 和 eas.json 配置项说明，包含所有可能的配置项和实际用例：

app.json 完整配置手册(Expo SDK 53)

{
  "expo": {
    // ========== 基础配置 ==========
    "name": "MyApp",                      // 应用名称（必填，显示在设备桌面）
    "slug": "my-app",                     // URL 标识符（必填，用于 expo publish）
    "owner": "your-username",             // 组织/个人账户名（多账户管理时需指定）
    "version": "1.0.0",                   // 用户可见版本号（语义化版本）
    "runtimeVersion": {
      "policy": "appVersion"              // OTA 更新策略 [sdkVersion|appVersion|nativeVersion]
    },
    "orientation": "portrait",            // 屏幕方向 [portrait|landscape|default]
    "privacy": "public",                  // 隐私设置 [public|unlisted|hidden]
    "platforms": ["ios", "android", "web"], // 目标平台

    // ========== 图标与界面 ==========
    "icon": "./assets/icon.png",          // 主图标（1024x1024 PNG，必填）
    "backgroundColor": "#ffffff",         // 通用背景色（用于启动屏过渡）
    "splash": {
      "image": "./assets/splash.png",     // 启动图（1242x2436 PNG）
      "resizeMode": "contain",            // [contain|cover|native]
      "backgroundColor": "#ffffff",       // 启动屏背景色
      "tabletImage": "./assets/splash-tablet.png" // iPad 专用启动图
    },
    "androidNavigationBar": {             // Android 导航栏配置
      "visible": "immersive",             // [leanback|immersive|sticky-immersive]
      "backgroundColor": "#000000"
    },

    // ========== Android 专属配置 ==========
    "android": {
      "package": "com.yourcompany.app",   // 包名（必填，反向域名格式）
      "versionCode": 1,                   // 整数版本号（每次提交递增）
      "adaptiveIcon": {                   // Android 8+ 自适应图标（必填）
        "foregroundImage": "./assets/adaptive-icon.png", // 前景图（108x108）
        "backgroundImage": "./assets/adaptive-bg.png",  // 背景图（可选）
        "backgroundColor": "#FFFFFF"      // 或纯色背景
      },
      "permissions": [                   // 精确权限控制（空数组表示不请求任何权限）
        "CAMERA",
        "android.permission.ACCESS_FINE_LOCATION",
        "RECORD_AUDIO"
      ],
      "blockedPermissions": [             // 显式屏蔽的权限
        "android.permission.READ_CONTACTS"
      ],
      "intentFilters": [                  // 深度链接配置
        {
          "action": "VIEW",
          "data": [
            {
              "scheme": "https",
              "host": "*.yourdomain.com",
              "pathPrefix": "/users"
            },
            {
              "scheme": "myapp",
              "host": "profile"
            }
          ],
          "category": ["BROWSABLE", "DEFAULT"]
        }
      ],
      "softwareKeyboardLayoutMode": "resize", // 键盘弹出行为 [resize|pan]
      "config": {
        "googleMaps": {                   // Google Maps API 配置
          "apiKey": "YOUR_GOOGLE_MAPS_KEY"
        }
      }
    },

    // ========== iOS 专属配置 ==========
    "ios": {
      "bundleIdentifier": "com.yourcompany.app", // Bundle ID（必填）
      "buildNumber": "1.0.0",             // 构建版本号（字符串）
      "supportsTablet": true,             // 是否支持 iPad
      "requireFullScreen": false,         // 是否强制全屏（iPad 多任务）
      "infoPlist": {                      // 自定义 Info.plist
        "NSLocationWhenInUseUsageDescription": "需要位置权限提供导航服务",
        "UIBackgroundModes": ["location", "fetch"],
        "ITSAppUsesNonExemptEncryption": false // 加密合规声明
      },
      "config": {
        "usesNonExemptEncryption": false, // 加密合规性
        "googleMapsApiKey": "YOUR_IOS_MAPS_KEY"
      },
      "entitlements": {                   // 特殊能力配置
        "aps-environment": "development", // 推送环境 [development|production]
        "com.apple.developer.networking.wifi-info": true
      },
      "usesAppleSignIn": true             // 是否启用 Apple 登录
    },

    // ========== Web 配置 ==========
    "web": {
      "favicon": "./assets/favicon.png",  // 网站图标（16x16 或 32x32 PNG）
      "bundler": "metro",                // 打包工具 [metro|webpack]
      "output": "static",                // 导出模式 [single|static]
      "lang": "en-US",                   // 默认语言
      "themeColor": "#ffffff",           // PWA 主题色
      "serviceWorker": {                 // PWA 配置
        "src": "./service-worker.js",
        "scope": "/",
        "useCache": true
      }
    },

    // ========== 插件配置 ==========
    "plugins": [
      "expo-camera",                     // 简单插件
      ["expo-notifications", {           // 带配置的插件
        "icon": "./assets/notif-icon.png",
        "color": "#ff0000",
        "sounds": ["./assets/notif-sound.wav"]
      }],
      ["expo-build-properties", {        // 原生构建配置覆盖
        "android": {
          "compileSdkVersion": 31,
          "targetSdkVersion": 31,
          "buildToolsVersion": "31.0.0"
        },
        "ios": {
          "deploymentTarget": "13.0"
        }
      }]
    ],

    // ========== 更新与资源 ==========
    "updates": {
      "enabled": true,                   // 是否启用 OTA
      "checkAutomatically": "ON_LOAD",   // [ON_LOAD|ON_ERROR_RECOVERY|WIFI_ONLY]
      "fallbackToCacheTimeout": 3000,    // 回退超时（毫秒）
      "url": "https://your-update-server.com" // 自定义更新服务器
    },
    "assetBundlePatterns": [             // 资源打包规则
      "**/*.png",
      "**/*.ttf",
      "fonts/**"
    ],

    // ========== 深度链接 ==========
    "scheme": "myapp",                   // 自定义协议 myapp://
    "detach": {                          // 分离模式配置（eject 时使用）
      "scheme": "detachedapp",
      "iosExpoViewUrl": "https://...",
      "androidExpoViewUrl": "https://..."
    },

    // ========== 额外配置 ==========
    "description": "应用描述（App Store/Play Store 展示）",
    "githubUrl": "https://github.com/your/repo",
    "primaryColor": "#6200ee",           // 主题色（Android 通知栏等）
    "extra": {                           // 自定义环境变量
      "apiUrl": "https://api.example.com",
      "encryptionKey": "@encryption_key" // 安全密钥（通过 app.config.js 注入）
    },
    "hooks": {                           // 构建钩子
      "postPublish": [
        {
          "file": "scripts/notify-slack.js",
          "config": {
            "channel": "#releases"
          }
        }
      ]
    }
  }
}

eas.json 完整配置手册

{
  "cli": {
    "version": ">= 3.0.0",              // 最低 EAS CLI 版本要求
    "promptToConfigurePushNotifications": true // 是否提示配置推送
  },
  "build": {
    // ===== 预设配置 =====
    "development": {
      "distribution": "internal",       // 分发类型 [internal|simulator|store]
      "developmentClient": true,        // 是否启用开发客户端
      "channel": "dev",                // 更新通道
      "env": {
        "API_URL": "https://dev.api.com"
      }
    },
    "preview": {
      "extends": "development",         // 继承其他配置
      "channel": "preview",
      "android": {
        "buildType": "apk"             // [apk|app-bundle]
      },
      "ios": {
        "simulator": true              // 是否构建模拟器版本
      }
    },
    "production": {
      "channel": "production",
      "distribution": "store",
      "releaseChannel": "prod-v1",
      "android": {
        "image": "ubuntu-18.04-android-30-ndk-r19c", // 构建镜像
        "buildType": "app-bundle",
        "gradleCommand": ":app:bundleRelease",
        "credentialsSource": "remote", // 凭证来源 [remote|local]
        "withoutCredentials": false
      },
      "ios": {
        "image": "macos-big-sur-11.4-xcode-12.5",
        "autoIncrement": "version",     // [version|buildNumber|none]
        "enterpriseProvisioning": "universal", // 企业证书类型
        "cache": {
          "key": "prod-{{ .Branch }}-{{ checksum "package-lock.json" }}",
          "paths": ["node_modules", "ios/Pods"]
        }
      },
      "env": {
        "API_URL": "https://prod.api.com",
        "FIREBASE_KEY": "@prod_firebase_key" // 安全变量
      }
    }
  },
  
  // ===== 提交配置 =====
  "submit": {
    "production": {
      "android": {
        "serviceAccount": "path/to/google-service-account.json",
        "track": "internal",           // [internal|alpha|beta|production|rollout]
        "releaseStatus": "completed",  // [draft|completed|halted|inProgress]
        "rolloutFraction": 0.25,      // 分阶段发布比例（0-1）
        "changesNotSentForReview": false // 是否跳过审核
      },
      "ios": {
        "appleId": "your@apple.id",
        "ascAppId": "1234567890",
        "appleTeamId": "ABCDEFGHIJ",
        "ascApiKeyPath": "path/to/AuthKey.p8",
        "ascApiKeyId": "KEY_ID",
        "ascApiKeyIssuerId": "ISSUER_ID",
        "appSpecificPassword": "@apple_app_password" // 双因素认证密码
      }
    }
  },
  
  // ===== 通用配置 =====
  "env": {                             // 全局环境变量
    "NODE_ENV": "production"
  },
  "experiments": {                     // 实验性功能
    "turboModules": true
  }
}

关键配置深度解析

1. Android 权限精细化控制

"android": {
  "permissions": [
    "CAMERA",
    "android.permission.ACCESS_BACKGROUND_LOCATION", // 精确指定权限
    {
      "name": "RECORD_AUDIO",
      "maxSdkVersion": 28 // 仅对 API 28 及以下设备请求
    }
  ],
  "blockedPermissions": [
    "android.permission.READ_EXTERNAL_STORAGE" // 显式屏蔽
  ]
}

2. iOS 后台模式配置

"ios": {
  "infoPlist": {
    "UIBackgroundModes": [
      "audio",           // 音频后台
      "location",        // 位置更新
      "fetch",           // 后台刷新
      "remote-notification" // 推送处理
    ],
    "NSPhotoLibraryAddUsageDescription": "需要保存图片到相册" // iOS 11+
  }
}

3. EAS 构建缓存优化

"cache": {
  "key": "{{ .OS }}-{{ .Branch }}-{{ checksum \"package-lock.json\" }}", // 动态缓存键
  "paths": [
    "node_modules",
    "android/.gradle",
    "ios/Pods",
    ".cache"
  ],
  "cacheDefaultPaths": false // 是否禁用默认缓存路径
}

4. 安全敏感变量处理

// 在 eas.json 中引用本地环境变量
"env": {
  "FIREBASE_KEY": "@firebase_prod_key" // 从 .env 或 eas secret 注入
}

// 终端命令添加密钥
eas secret:create --name firebase_prod_key --value your_key

5. 多环境配置策略

// app.config.js 动态配置
module.exports = ({ config }) => {
  const isProd = process.env.APP_ENV === "production";
  return {
    ...config,
    extra: {
      apiUrl: isProd ? "https://prod.api" : "https://dev.api",
      enableAnalytics: isProd
    },
    android: {
      ...config.android,
      versionCode: isProd ? 100 : 1
    }
  };
};

完整工作流示例

1. 开发构建

# 生成开发版 APK
eas build --platform android --profile development

# 启动开发服务器
expo start --dev-client

2. 生产发布

# 设置生产环境密钥
eas secret:create --name api_prod_key --value xyz123

# 构建并提交到商店
eas build --platform all --profile production
eas submit --platform ios --profile production

3. OTA 更新管理

# 发布更新到 production 通道
expo publish --release-channel prod-v1

# 回滚到指定版本
expo publish --release-channel prod-v1 --republish

SDK 53 特别注意事项

  1. React Native 兼容性
  2. // package.json 必须匹配
    "react-native": "0.63.4",
    "expo": "~53.0.7",
    "react": "16.13.1"
  3. 遗留配置迁移
  4. exp.json → app.json (SDK 53 已完全弃用旧格式)
  5. expo.ios.config.googleSignIn 已移至插件 expo-google-sign-in
  6. 弃用警告
  7. expo.assetBundlePatterns 中的 !**/*.mp4 语法已弃用，改用 android.packagingOptions

app.json根级配置

字段

类型

说明

示例

name

string

应用名称（显示在设备主屏幕）

"MyApp"

slug

string

URL 唯一标识（用于 OTA 更新和分享链接）

"my-app"

version

string

应用版本号（语义化版本）

"1.0.0"

orientation

string

屏幕方向："portrait"（竖屏）、"landscape"（横屏）

"portrait"

icon

string

应用图标路径（推荐 1024×1024 PNG）

"./assets/icon.png"

splash

object

启动屏配置（含 image、resizeMode 等）

见下方示例

platforms

array

支持平台：["ios", "android", "web"]

["ios", "android"]

plugins

array

插件列表（如 ["expo-camera"]）

["expo-location"]

extra

object

自定义环境变量（通过 expo-constants 访问）

{ "apiUrl": "https://api.example.com" }

标签：signapk 

作者:alicucu , 分类:技术文章 , 浏览:1 , 评论:0

控制面板
您好，欢迎到访网站！
  查看权限
网站分类
最新留言