完整指南：从零开始，无需本地环境

一、前言

开发 Android 应用时，打包 APK 通常需要在本地配置 Android Studio、JDK、Android SDK 等工具链，整个过程繁琐且耗时。如果你只是想简单地构建一个 APK 文件，安装到手机上测试，是否有更简单的方法？

答案是：有！GitHub Actions 可以帮你在云端自动构建 APK。你只需要把代码推送到 GitHub，剩下的事 GitHub 会自动完成--完全不需要本地安装任何工具。

本文将以一个真实的项目为例，手把手教你如何使用 GitHub Actions 自动打包 Android APK。

二、效果预览

完成后，你将获得：

推送代码到 GitHub 后自动触发构建
构建完成后可直接下载 APK 文件
支持手动触发构建（无需推送代码）
完全免费，使用 GitHub 提供的云端资源

三、项目结构

在开始之前，先了解一下我们需要的文件结构。一个标准的 Android 项目需要以下关键文件：

bash 复制代码

RingtoneApp/

├── .github/

│ └── workflows/

│ └── build.yml # GitHub Actions 工作流配置

├── app/

│ ├── build.gradle.kts # 应用构建配置

│ └── src/main/

│ ├── AndroidManifest.xml # 应用清单

│ └── java/.../MainActivity.kt # Kotlin 源码

├── build.gradle.kts # 项目级构建配置

├── settings.gradle.kts # 项目设置

└── gradle.properties # Gradle 属性

四、核心：GitHub Actions 工作流

关键就在于创建一个 YAML 配置文件，告诉 GitHub 如何构建你的项目。创建文件：

bash 复制代码

.github/workflows/build.yml

4.1 完整工作流配置

以下是一个可直接使用的完整配置，我会逐行解释每个部分的作用：

yaml 复制代码

name: Build APK
 
on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]
  workflow_dispatch:  # 允许手动触发
 
env:
  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
 
jobs:
  build:
    runs-on: ubuntu-latest
 
    steps:
      - uses: actions/checkout@v4
 
      - name: Set up JDK 17
        uses: actions/setup-java@v4
        with:
          java-version: '17'
          distribution: 'temurin'
 
      - name: Setup Android SDK
        uses: android-actions/setup-android@v3
 
      - name: Build Debug APK
        run: ./gradlew assembleDebug
 
      - name: Upload APK
        uses: actions/upload-artifact@v4
        with:
          name: RingtoneApp-debug
          path: app/build/outputs/apk/debug/app-debug.apk

4.2 配置详解

on：触发条件

push / pull_request：当 main 分支有代码推送或 PR 时自动构建
workflow_dispatch：允许在 GitHub 网页上手动点击触发，无需推送代码

steps：构建步骤

actions/checkout@v4：拉取代码到运行器
setup-java@v4：安装 JDK 17（Android 构建必需）
setup-android@v3：安装 Android SDK 和构建工具
./gradlew assembleDebug：执行 Gradle 构建，生成 debug APK
upload-artifact@v4：将生成的 APK 上传为可下载的构建产物

小贴士

env 中的 FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true 是为了消除 Node.js 版本警告，不加也不影响构建。

五、项目配置文件

除了工作流文件，项目本身的配置也非常重要。以下是几个关键配置文件的说明。

5.1 gradle.properties（必须）

这个文件缺少会导致构建失败，必须添加：

bash 复制代码

\# 启用 AndroidX

android.useAndroidX=true

\# 自动迁移第三方库到 AndroidX

android.enableJetifier=true

5.2 build.gradle.kts（项目级）

javascript 复制代码

plugins {

id("com.android.application") version "8.2.0" apply false

id("org.jetbrains.kotlin.android") version "1.9.20" apply false

}

5.3 app/build.gradle.kts（应用级）

javascript 复制代码

plugins {

id("com.android.application")

id("org.jetbrains.kotlin.android")

}

android {

namespace = "com.example.ringtoneapp"

compileSdk = 34

defaultConfig {

applicationId = "com.example.ringtoneapp"

minSdk = 26

targetSdk = 34

versionCode = 1

versionName = "1.0"

}

compileOptions {

sourceCompatibility = JavaVersion.VERSION_1_8

targetCompatibility = JavaVersion.VERSION_1_8

}

kotlinOptions {

jvmTarget = "1.8"

}

}

dependencies {

implementation("androidx.core:core-ktx:1.12.0")

implementation("androidx.appcompat:appcompat:1.6.1")

implementation("com.google.android.material:material:1.11.0")

implementation("androidx.constraintlayout:constraintlayout:2.1.4")

implementation("androidx.recyclerview:recyclerview:1.3.2")

}

5.4 settings.gradle.kts

javascript 复制代码

pluginManagement {

repositories {

google()

mavenCentral()

gradlePluginPortal()

}

}

dependencyResolutionManagement {

repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)

repositories {

google()

mavenCentral()

}

}

rootProject.name = "RingtoneApp"

include(":app")

5.5 gradlew（Gradle Wrapper 启动脚本）

如果项目中没有 gradlew 文件，需要创建一个简单的启动脚本：

!/bin/sh

exec gradle "$@"

注意

创建后要执行 chmod +x gradlew 赋予执行权限。GitHub Actions 中的 ubuntu-latest 环境已预装 Gradle，所以这个简化脚本就够用了。

六、常见问题与解决方案

在实际操作中，我遇到了以下几个问题，在此分享解决方案，希望能帮到你。

问题 1：AndroidX 依赖错误

错误信息：

Configuration :app:debugRuntimeClasspath contains AndroidX dependencies,

but the android.useAndroidX property is not enabled.

解决方案：

在项目根目录创建 gradle.properties 文件，添加：

android.useAndroidX=true

android.enableJetifier=true

问题 2：资源文件找不到

错误信息：

AAPT: error: resource mipmap/ic_launcher not found.

解决方案：

在 res/mipmap-anydpi-v26/ 目录下创建 ic_launcher.xml 和 ic_launcher_round.xml，使用 Adaptive Icon：

bash 复制代码

&lt;!-- res/mipmap-anydpi-v26/ic_launcher.xml --&gt;

&lt;?xml version="1.0" encoding="utf-8"?&gt;

&lt;adaptive-icon xmlns:android="<http://schemas.android.com/apk/res/android>"&gt;

&lt;background android:drawable="@color/gradient_start" /&gt;

&lt;foreground&gt;

&lt;inset android:drawable="@drawable/ic_bell" android:inset="25%" /&gt;

&lt;/foreground&gt;

&lt;/adaptive-icon&gt;

问题 3：Kotlin 类型不匹配

错误信息：

The integer literal does not conform to the expected type Double

解决方案：

Kotlin 中 coerceAtLeast() 的参数类型必须与变量类型一致。将整数改为浮点数：

// 错误写法

val attack = (total * 0.05).coerceAtLeast(10)

// 正确写法

val attack = (total * 0.05).coerceAtLeast(10.0)

问题 4：Node.js 版本警告

警告信息：

Node.js 20 actions are deprecated...

解决方案：

在工作流文件中添加环境变量：

env:

FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true

七、完整操作步骤

按照以下步骤操作，你可以从零开始完成整个流程：

步骤 1：创建 GitHub 仓库

登录 GitHub，点击 "New repository"
填写仓库名称（如 RingtoneApp）
选择 Private 或 Public
不要勾选 "Add a README" 等初始化选项
点击 "Create repository"

步骤 2：创建项目文件

在本地创建以下文件结构，内容参考本文第三、四、五节：

bash 复制代码

mkdir -p .github/workflows

mkdir -p app/src/main/java/com/example/yourapp

mkdir -p app/src/main/res/{layout,values,drawable,mipmap-anydpi-v26}

创建各配置文件...

步骤 3：推送到 GitHub

bash 复制代码

cd your-project

git init

git add -A

git commit -m "Initial commit"

git remote add origin <https://github.com/你的用名/仓库名.git>

git branch -M main

git push -u origin main

步骤 4：触发构建

推送成功后，GitHub 会自动触发构建。你也可以手动触发：

进入仓库页面，点击 "Actions" 标签
左侧选择 "Build APK"
点击 "Run workflow" → "Run workflow"

步骤 5：下载 APK

构建完成后（约 2-3 分钟），点击该次构建记录
在页面底部找到 "Artifacts" 区域
点击 "RingtoneApp-debug" 下载 ZIP 压缩包
解压后得到 app-debug.apk，可直接安装到手机

提示

Artifacts 有保存期限（90 天），建议及时下载。如果过期，重新触发一次构建即可。

八、总结

通过 GitHub Actions 自动打包 Android APK，你可以获得以下优势：

方面	优势
环境要求	零--只需要一个 GitHub 账号
成本	完全免费，GitHub 提供每月 2000 分钟构建时间
自动化	推送代码即自动构建，无需手动操作
协作	团队成员可直接下载最新构建产物

如果你在实践中遇到其他问题，欢迎在评论区留言交流。希望本文能帮助到你！

参考链接

GitHub Actions 官方文档：https://docs.github.com/cn/actions
Android Gradle 插件指南：https://developer.android.com/build
本文示例项目：https://github.com/lgeger/RingtoneApp