构建安装包

约 849 字大约 3 分钟

2026-01-22

一、用原生方法把Expo项目打包成APK

构建 Android 安装包

1. 运行 `yarn expo prebuild` 命令，生成 Android 项目。

2. 进入目录 `android`。

android
- build.gradle // 项目的构建配置文件
- gradle.properties // 项目的 Gradle 配置文件
- settings.gradle // 项目的设置配置文件
- gradlew.bat // Windows 下的 Gradle 包装脚本
- gradlew // Linux/Mac 下的 Gradle 包装脚本
- local.properties // 项目的本地配置文件, 包含 Android SDK 路径等信息(没有可自行创建)

2.1 推荐方式：使用 `app.json/app.config.js` 配置（无需手动改 build.gradle）

从 Expo SDK 46+ 开始，官方推荐通过 expo-build-properties 插件在 app.json 中配置常见构建选项，避免直接修改原生文件（减少冲突、便于升级）。

示例：app.json

{
  "expo": {
    "plugins": [
      [
        "expo-build-properties",
        {
          "android": {
            "compileSdkVersion": 34,
            "targetSdkVersion": 34,
            "minSdkVersion": 21,
            "buildToolsVersion": "34.0.0",
            "kotlinVersion": "1.9.20",
            "gradleVersion": "8.5",
            "enableProguardInReleaseBuilds": true,
            "extraProguardRules": "-keep class com.example.** { *; }"
          }
        }
      ]
    ]
  }
}

✅ 修改后运行 npx expo prebuild --clean 会自动同步到 android/app/build.gradle。

2.2 手动修改 `android/app/build.gradle`（仅在必要时）

如果你确实需要手动编辑（例如添加自定义依赖、配置签名、多渠道等），以下是 Expo 生成的 android/app/build.gradle 的典型结构和关键配置项说明：

apply plugin: "com.android.application"
apply plugin: "org.jetbrains.kotlin.android"

// 注意：Expo 使用 apply from 引入其预设配置
apply from: new File(["node", "--print", "require.resolve('expo/package.json')"].execute(null, rootDir).text.trim(), "../scripts/autolinking.gradle")
apply from: new File(["node", "--print", "require.resolve('expo/package.json')"].execute(null, rootDir).text.trim(), "../scripts/react.gradle")

android {
    ndkVersion rootProject.ext.ndkVersion
    compileSdkVersion rootProject.ext.compileSdkVersion

    namespace "your.bundle.identifier" // Expo 从 app.json 的 android.package 自动填充

    defaultConfig {
        applicationId "your.bundle.identifier"
        minSdkVersion rootProject.ext.minSdkVersion
        targetSdkVersion rootProjected.ext.targetSdkVersion
        versionCode 1
        versionName "1.0"
    }

    signingConfigs {
        debug {
            storeFile file('debug.keystore')
            storePassword 'android'
            keyAlias 'androiddebugkey'
            keyPassword 'android'
        }
        // release 签名通常通过 gradle.properties 或环境变量注入
    }

    buildTypes {
        debug {
            signingConfig signingConfigs.debug
        }
        release {
            signingConfig signingConfigs.debug // 注意：生产应替换为正式签名
            minifyEnabled enableProguardInReleaseBuilds
            proguardFiles getDefaultProguardFile("proguard-android.txt"), "proguard-rules.pro"
        }
    }

    // Kotlin 兼容性
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_17
        targetCompatibility JavaVersion.VERSION_17
    }

    kotlinOptions {
        jvmTarget = "17"
    }
}

dependencies {
    // Expo 自动注入核心依赖
    implementation("com.facebook.react:react-android")

    // Autolinking 会自动添加其他 Expo 模块依赖
}

配置项	来源	说明
`compileSdkVersion`, `minSdkVersion`, `targetSdkVersion`	`rootProject.ext`（来自 `android/build.gradle`）	建议通过 `expo-build-properties` 插件控制
`namespace`	来自 `app.json` 的 `android.package`	必须与 Google Play 上已发布应用一致
`signingConfigs`	手动配置或通过 CI 注入	生产构建必须配置正式签名
`enableProguardInReleaseBuilds`	来自 `project.hasProperty('enableProguardInReleaseBuilds')`	可通过 `gradle.properties` 或 `expo-build-properties` 控制

2.3 `android/build.gradle`（项目级）

此文件定义全局 Gradle 插件版本和仓库：

buildscript {
    ext {
        // 这些值会被 app/build.gradle 引用
        buildToolsVersion = findProperty('android.buildToolsVersion') ?: '34.0.0'
        minSdkVersion = Integer.parseInt(findProperty('android.minSdkVersion') ?: '21')
        compileSdkVersion = Integer.parseInt(findProperty('android.compileSdkVersion') ?: '34')
        targetSdkVersion = Integer.parseInt(findProperty('android.targetSdkVersion') ?: '34')
        kotlinVersion = findProperty('kotlinVersion') ?: '1.9.20'
        // ...
    }

    repositories {
        google()
        mavenCentral()
    }

    dependencies {
        classpath('com.android.tools.build:gradle:8.5.0')
        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin: $ kotlinVersion")
    }
}

allprojects {
    repositories {
        maven {
            url " $ rootDir/../node_modules/expo-router/node_modules/expo/maven"
        }
        // 其他 Expo 模块的本地 maven 仓库
        google()
        mavenCentral()
    }
}

💡 注意：Expo 会通过脚本动态注入本地 node_modules 中的 Maven 仓库路径，用于支持 autolinking。

3. 构建安装包，需配置 JDK、Android SDK、NDK、CMake 等环境, 可通过 Android Studio 配置, 然后通过 `local.properties` 文件指定路径。

## This file must *NOT* be checked into Version Control Systems,
# as it contains information specific to your local configuration.
#
# Location of the SDK. This is only used by Gradle.
# For customization when using a Version Control System, please read the
# header note.
#Thu Jan 22 00:00:00 CST 2026
sdk.dir=C:\\sofeware\\Android\\SDK

# 在 这里设置没用， 还是会使用默认的 JDK 版本
org.gradle.java.home=C:\\Users\\lfang\\.jdks\\ms-17.0.17

# NDK home
ndk.dir=C:\\sofeware\\Android\\SDK\\ndk\\27.0.12077973

# CMake home
cmake.dir=C:\\sofeware\\Android\\SDK\\cmake\\3.22.1

4. 运行构建命令

// 查看构建版本
./gradlew version

# 构建 debug APK
./gradlew assembleDebug

# 构建 release APK（需签名配置）
./gradlew assembleRelease

# 构建 AAB（用于 Google Play）
./gradlew bundleRelease