摸着石头过河，重新支棱起Capacitor老项目

背景

最近接手了一个混合移动应用项目，使用的混合框架是Capacitor。先简明扼要的介绍一下Capacitor。Capacitor是由 Ionic 团队开发的一款跨平台 Web-Native 桥接框架，用于将 Web 应用（如 Vue、React、Angular）打包成原生 iOS、Android、Electron 应用。H5页面的功能开发完了，老板要拿出去给客户演示，给客户发一个链接打开H5应用显得有点low, 所以产品经理希望能做成App应用。我看了一下这个项目中package.json中的脚本命令，发现有生成Android应用安装包的相关指令，之前写这个项目的人离职了，没人熟悉如何编译生成apk安装包，在我之前有个同事调研了一天，包打出来了，但是安装之后一片空白，他短时间内未能解决，不了了之。我对工作一般是正向思考，觉得这是个不错的在实际项目中练手的好机会，产品再次提及时主动认领了这个工作任务，于是就有了这篇文章。

第一步熟悉Capacitor常用指令

如何开始? 在项目中的package.json看到这么一条指令:

js 复制代码

"open-android": "npx cap sync && npx cap open android",

看样子是跟打包Android apk安装包有关，以此为线索，开启摸着石头过河之旅。一般要想了解一条指令，就得了解这条指令背后的一连串相关指令。让我们看看Capacitor常用的指令有哪些？

指令功能	指令
安装 Capacitor	npm install @capacitor/core @capacitor/cli
初始化项目	npx cap init appName app.id
添加平台	npx cap add android npx cap add ios
将构建Web资源复制到原生项目中	npx cap copy
复制 Web 资源 + 同步插件/依赖	npx cap sync
打开 Android Studio / Xcode	npx cap open android npx cap open ios

所以上面指令的含义是复制构建好的Web资源 + 同步插件/依赖到原生项目，并打开Android-Studio，再Android-Studio中对项目进行编译打包，生成Android应用安装包。

第二步搭建Android开发环境

搭建Android开发环境是以Android-Studio为中心展开的。包括Android-Studio的下载-->安装-->配置-->新建/导入项目-->运行和调试。

重点是第三步的配置，国内开发者要对项目做两个配置:

因为国内的网络环境可能会导致访问国外 Maven 仓库较慢或不稳定，为了提升gradle依赖库下载速度,需要将Maven仓库替换成阿里云的镜像。确保能够顺利从镜像源获取所需的库和工具.

在android/build.gradle（根目录）下的 repositories 里面添加

rust 复制代码

allprojects {
    repositories {
        maven { url 'https://maven.aliyun.com/repository/google' }
        maven { url 'https://maven.aliyun.com/repository/jcenter' }
        maven { url 'https://maven.aliyun.com/repository/central' }
        google()
        mavenCentral()
    }
}

因为 Gradle 的官方镜像服务器位于国外，国内用户访问时可能会遇到较慢的下载速度或连接不稳定的情况，尤其是初次设置或更新 Gradle 版本时，通过使用腾讯云的镜像源，国内用户能够更快速地下载 Gradle 发行版。

在android/gradle/wrapper/gradle-wrapper.properties，做如下修改

ini 复制代码

distributionUrl=https://mirrors.cloud.tencent.com/gradle/gradle-7.5-all.zip

第三步熟悉Android项目目录结构

初次接触Android项目，对Android项目每个文件夹，每个文件的作用肯定是不清楚的，有必要了解一下什么资源放置在什么地方。典型的Android项目目录如下：

md 复制代码

android/
├── .gradle/
├── .idea/
├── app/
│   ├── build/
│   ├── libs/
│   ├── src/
│   │   ├── androidTest/
│   │   ├── main/
│   │   │   ├── java/
│   │   │   ├── res/
│   │   │   └── AndroidManifest.xml
│   │   └── test/
│   ├── build.gradle
│   └── proguard-rules.pro
├── build/
├── gradle/
├── gradle.properties
├── gradlew
├── gradlew.bat
├── settings.gradle
└── build.gradle

每个目录和文件说明如下：菜鸟务必要从头到尾看一遍，有个初步印象。

android/ ：项目的根目录

.gradle/ ：Gradle 构建工具的缓存目录，存储构建过程中产生的临时文件。
.idea/ ：存放与项目相关的 IntelliJ IDEA（Android Studio 基于此）配置文件。
app/ ：应用模块的目录，包含应用的源代码和资源文件。
- build/ ：编译时自动生成的目录，包含构建输出，如 APK 文件。
- libs/ ：用于存放第三方库的目录，放置 .jar 或 .aar 文件。
- src/ ：源代码目录，包含应用的代码和资源。
  - androidTest/ ：用于存放针对 Android 设备的集成测试代码。
  - main/ ：主源代码集，包含应用的主要代码和资源。
    - java/ ：存放 Java 或 Kotlin 源代码。
    - res/ ：存放应用的资源文件，如布局、图片和字符串等。
    - AndroidManifest.xml：应用的清单文件，描述应用的基本信息和组件。
  - test/ ：用于存放本地单元测试代码。
- build.gradle：模块级的 Gradle 构建脚本，定义模块的构建配置和依赖项。
- proguard-rules.pro：ProGuard 混淆规则文件，用于代码混淆配置。
build/ ：项目级的构建输出目录，存放构建过程中生成的文件。
gradle/ ：Gradle Wrapper 的目录，包含用于构建的 Gradle 包装器文件。
gradle.properties：Gradle 的属性配置文件，用于设置构建相关的属性。
gradlew 和 gradlew.bat：用于在不同操作系统上执行 Gradle 构建的脚本文件。
settings.gradle：项目的设置文件，定义包含在构建中的模块。
build.gradle：项目级的 Gradle 构建脚本，定义全局的构建配置和依赖项。

看完android项目的目录和文件介绍之后，你会发现有个名词gradle，出现的频率特别高，这个gradle是什么东东,和android开发有什么关系，为什么还区分模块和项目级别？

Gradle 是一个强大的构建自动化工具，广泛应用于软件开发中，包括 Android 应用的编译，测试和打包。与传统的 XML 配置方式不同，Gradle 使用基于 Groovy 或 Kotlin 的领域特定语言（DSL）来编写构建脚本，使其更具灵活性和可读性。在 Android 开发中，Gradle 通过 Android Gradle 插件（AGP）与 Android Studio 集成，为开发者提供了灵活高效的构建系统。

Gradle 与 Android 的关系：

构建系统基础：Android Studio 的构建系统以 Gradle 为基础，利用其灵活性和可扩展性来管理应用的构建过程。
Android Gradle 插件（AGP） ：AGP 是专为构建 Android 应用而设计的 Gradle 插件，提供了许多特定于 Android 的功能，如生成 APK 文件、管理 Android 特定的依赖项等。
版本兼容性：确保 AGP 与 Gradle 版本的兼容性对于构建过程的顺利进行至关重要。不同版本的 AGP 需要对应的 Gradle 版本支持。

在 Gradle 中，构建脚本通常分为项目级和模块级两个层次，分别对应于不同的配置范围：

级别	位置	作用
项目级	位于项目的根目录	定义整个项目的全局构建配置和依赖项，这些设置适用于项目中的所有模块。用于配置全局的插件、依赖库仓库等
模块级	位于每个模块的目录中	针对各个模块进行具体的构建配置，如应用的版本信息、特定的依赖项等。这些设置仅适用于各自的模块。用于指定该模块的编译选项、资源文件夹等。

这种区分使得构建配置更具层次性和灵活性，有助于在大型、多模块项目中更好地管理构建过程。

第四步打包与测试Android apk

清除上一次编译文件并重新打包web资源

bash 复制代码

rm -rf android/app/src/main/assets/public && pnpm run build

复制 Web 资源 + 同步插件/依赖到Android原生项目，打开Android-Studio

bash 复制代码

npx cap sync && npx cap open android

在Android-Studio中构建apk安装包

在菜单栏中，选择 Build -> Build Bundle / APK -> Build APK(s)，构建过程完成后，访问 app/build/outputs/apk/ 目录下找到生成的 APK 文件。

在手机上安装应用包

将Android手机设置成USB调试模式,执行adb devices,查看设备是否连接成功。如果连接不成功，检查一下数据线与电脑USB接口的连接处是不是松了，还有是否在手机上已经授权电脑访问。连接上之后，切换到apk目录，在终端下执行应用包的安装指令

bash 复制代码

adb install -r app-debug.apk

安装完之后，打开发现页面一片空白，遇到了跟同事一模一样的问题。离成功只差一步之遥了，这次必须解决。

解决界面白屏问题

用 chrome inspect调试了一下，发现是资源路径不对。改了一下capacitor.config.ts中server.url配置，让其访问线上环境，问题解决。

js 复制代码

import { CapacitorConfig } from '@capacitor/cli';
const config: CapacitorConfig = {
  // ...
  server: {
    url: 'https://xxx/path',
    cleartext: false,
  },
};
export default config;

如果想要项目执行打包进apk中的web资源逻辑,需要改两处：

修改vite.config.ts中的资源基础路径

js 复制代码

export default defineConfig(({ command }) => {
  return {
    base: './',
  }
}

注释掉capacitor.config.ts中server.url配置

js 复制代码

import { CapacitorConfig } from '@capacitor/cli';
const config: CapacitorConfig = {
  // ...
  server: {
    // url: 'https://xxx/path',
    cleartext: true,
  },
};
export default config;

至此，打包出了一个可以正常安装使用的Android应用。开心三分钟，今天过得比较充实，所谓的充实，就是心灵有收获感。希望你读完此文也收获充实感。

摸着石头过河，重新支棱起Capacitor老项目

背景

第一步 熟悉Capacitor常用指令

第二步 搭建Android开发环境

第三步 熟悉Android项目目录结构

第四步 打包与测试Android apk

第一步熟悉Capacitor常用指令

第二步搭建Android开发环境

第三步熟悉Android项目目录结构

第四步打包与测试Android apk