共计 3228 个字符，预计需要花费 9 分钟才能阅读完成。
引言
很多人想把自己的网页项目打包成手机 APP，但一想到要学 Java、配 Android Studio、折腾 Gradle，就打了退堂鼓。其实有个更简单的方式——用 GitHub Actions 在云端自动构建 APK，全程不用碰 Android 开发环境，最后直接在手机上下载安装即可。
本文以我自己的 ” 正点闹钟 ” 项目为例，手把手演示如何把纯 HTML/CSS/JS 网页项目转成可安装的 Android APP。
技术方案
核心工具是 Capacitor 和 GitHub Actions：
- Capacitor：把网页包进原生 Android 项目壳里，支持调用手机硬件（震动、通知等）
- GitHub Actions：GitHub 提供的免费 CI/CD 服务，每次 push 代码后自动在云端编译 APK
整个流程是：网页项目 → Capacitor 包装 → 推送到 GitHub → Actions 自动构建 → 下载 APK → 手机安装
前提条件
- 一个已有的网页项目（HTML/CSS/JS，单页或多页都可以）
- GitHub 账号
- 手机（Android）能安装未知来源应用
不需要本地装 Android Studio，不需要懂 Java。
步骤一：初始化 Capacitor 项目
在项目根目录执行以下命令：
# 1. 初始化 npm 项目（如果还没有 package.json）npm init -y
# 2. 安装 Capacitor 核心依赖
npm install @capacitor/core @capacitor/cli @capacitor/android
创建配置文件
新建 capacitor.config.json：
{
"appId": "com.yourname.app",
"appName": "你的 APP 名称",
"webDir": "www",
"plugins": {
"SplashScreen": {
"launchShowDuration": 2000,
"backgroundColor": "#1a1a2e"
}
}
}
注意 webDir 指向你的网页资源目录。我把项目文件放到了 www/ 文件夹下。
生成 Android 原生项目
npx cap add android
这会在当前目录生成一个 android/ 文件夹，里面就是完整的 Gradle + Android 项目结构。
步骤二：配置需要的权限
编辑 android/app/src/main/AndroidManifest.xml，在 </manifest> 前添加手机功能权限：
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.VIBRATE" />
<uses-permission android:name="android.permission.WAKE_LOCK" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
如果你做了闹钟类应用，这些权限能让震动、响铃、通知正常工作。
步骤三：配置 GitHub Actions 自动构建
在项目根目录创建文件：.github/workflows/build-apk.yml
name: Build APK
on:
push:
branches: [main, master]
workflow_dispatch:
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 Node.js
uses: actions/setup-node@v4
with:
node-version: '20'
cache: 'npm'
- name: Install dependencies
run: npm ci
- name: Sync Capacitor Android
run: npx cap sync android
- name: Grant execute permission for gradlew
run: chmod +x android/gradlew
- name: Build Release APK
run: cd android && ./gradlew assembleRelease
- name: Upload APK
uses: actions/upload-artifact@v4
with:
name: app-apk
path: android/app/build/outputs/apk/release/app-release-unsigned.apk
这个配置做了这几件事：
- 每次 push 到 main 分支时自动触发
- 在 Ubuntu 服务器上安装 JDK 17 和 Node.js 20
- 执行
npm ci安装依赖 - 同步 Capacitor Android 资源
- 用 Gradle 构建 Release APK
- 把生成的 APK 文件上传到 Artifacts，供下载
步骤四：推送到 GitHub 并触发构建
初始化 Git 仓库并推送：
git init
git add .
git commit -m "Initial commit"
git branch -M main
git remote add origin https://github.com/ 你的用户名 / 你的仓库名.git
git push -u origin main
Push 成功后，打开 GitHub 仓库页面 → Actions 标签，就能看到构建正在运行。
步骤五：下载 APK 并安装到手机
构建完成后（约 3-5 分钟）：
- 进入 Actions 页面，点击那次成功的构建记录
- 页面底部找到 Artifacts 区域
- 点击下载 ZIP 文件，解压得到
.apk - 把 APK 传到手机上（微信文件传输、数据线、网盘都行）
- 手机上点击安装，允许 ” 未知来源应用 ”
因为是未签名 APK，安装时会有安全提示，属于正常现象，点继续安装即可。
常见问题
Q1: npm ci 报 “lock file mismatch” 错误
这是因为 package.json 修改后没有同步更新 package-lock.json。解决方法是删除 lock 文件重新生成：
rm package-lock.json
npm install
Q2: 构建时间太长
第一次构建需要下载 Gradle 依赖和 Android SDK，可能需要 5-8 分钟。后续构建会快很多。
Q3: 想给 APK 签名，避免 ” 未知来源 ” 提示
可以用 GitHub Secrets 配置签名密钥。在 workflow 中加入签名步骤，需要生成一个 keystore 文件并配置到仓库的 Secrets 里。详细步骤参考 Capacitor 官方文档的签名章节。
Q4: 安装后 APP 闪退
检查 webDir 路径是否正确，确保所有资源文件（CSS、JS、图片）都已放入对应目录，并在 npx cap sync 后正确同步到了 android 项目的 assets 里。
进阶：签名 APK
如果你希望 APK 有正式签名，在 GitHub 仓库设置中添加 4 个 Secrets：
SIGNING_KEY：keystore 文件的 Base64 编码ALIAS：密钥别名KEY_STORE_PASSWORD：密钥库密码KEY_PASSWORD：密钥密码
然后在 workflow 中加入签名步骤，就能构建出签名版 APK，安装体验更顺畅。
总结
用 Capacitor + GitHub Actions 把网页转成手机 APP，核心优势是 零本地配置：
- 不需要安装 Android Studio
- 不需要懂 Java 或 Gradle
- 不需要本地配 JDK 和 Android SDK
- 所有构建在云端完成，手机直接下载安装
对于个人项目、原型验证、或者不想折腾原生开发环境的人来说，这是最省事的方案。
