企业官网建设流程全解析

Carrier IMS for Pixel（TurboIMS）是一款面向 Google Pixel 系列手机的运营商配置与 IMS 调优工具集，基于 Shizuku 实现 VoLTE、VoWiFi、VoNR、5G+ 显示等能力的一键开关。本文是一份从零出发的完整开发者指南：带你完成Gradle 配置解读、本地签名配置、adb 部署上机三大核心环节，10 分钟即可构建出可安装的 APK，并理解整个发布流程。

一、构建环境准备：版本要求一览

先确认你的开发环境满足以下要求，避免 90% 的"神秘构建失败"：

💡 所有版本号集中定义在 gradle/libs.versions.toml，这是 Gradle 的"版本目录"（Version Catalog）机制——升级任一依赖，只需改这一个文件。

二、一键克隆：获取源码与项目结构速览

git clone https://gitcode.com/gh_mirrors/ca/carrier-ims-for-pixel cd carrier-ims-for-pixel

项目为双模块结构，在 settings.gradle.kts 中声明：

• :app—— 主应用模块（Compose UI + Shizuku 权限层）
• :stub—— AIDL 桩库，仅供编译期引用（compileOnly），不参与打包

⚠️关键细节：构建脚本会通过git rev-list命令推导 versionCode（提交总数）与 versionName 后缀（短哈希），见 app/build.gradle.kts。因此不能用 zip 下载源码后构建，必须git clone获得 git 历史，否则构建会直接报错。

当前应用版本为 3.9.0（app-version字段），历史变更可查 CHANGELOG.md。

三、Gradle 配置详解：读懂 4 个核心文件

3.1 根配置与依赖仓库

settings.gradle.kts 将插件仓库限定为google()+mavenCentral()，并开启FAIL_ON_PROJECT_REPOS模式——所有依赖解析只走这里声明的仓库，保证构建可复现、不受子模块"私藏仓库"干扰。

3.2 应用模块:app

app/build.gradle.kts 中有几个值得注意的配置点：

• 包名与安装 ID：namespace 为io.github.vvb2060.ims，实际安装 ID（applicationId）为io.github.vvb2060.ims.mod。可通过 Gradle 属性turboims.debugApplicationIdSuffix或环境变量TURBOIMS_DEBUG_APPLICATION_ID_SUFFIX给 debug 版加后缀，实现与正式包并行安装，见 app/build.gradle.kts
• 只打包 arm64-v8a：Pixel 全系为 ARM 架构，ndk.abiFilters收窄 ABI 可显著减小 APK 体积
• 语言裁剪：androidResources.localeFilters仅保留en与zh-rCN，进一步瘦身
• Compose 构建：启用buildConfig与compose构建特性

3.3 桩库模块:stub

stub/build.gradle.kts 极简：一个启用 AIDL 的 Android Library。它承载 app/src/main/AndroidManifest.xml 中声明的 8 个instrumentation组件所需的系统接口桩——App 借此以 Shizuku 提权方式读写 CarrierConfig、触发 IMS 注册。

3.4 全局构建参数

gradle.properties 开启了并行构建与构建缓存，并为 Gradle 守护进程分配 4GB 堆内存、Kotlin 守护进程 3GB，大型首次构建更稳。

四、本地签名配置：4 步写好 local.properties 🔑

项目不使用 debug 默认签名，而是debug 与 release 共用同一个自定义签名配置sign，由 signing.gradle 在构建末尾注入：

加载优先级：local.properties中的SIGN_*键 → 系统环境变量（前者缺失时才回退到环境变量）。

Step 1：生成 keystore

keytool -genkeypair -alias turboims -keyalg RSA -keysize 2048 -validity 10000 \ -keystore turboims.keystore

Step 2：在工程根目录的local.properties中补齐 4 个键

SIGN_KEY_STORE_FILE=/绝对路径/turboims.keystore SIGN_KEY_STORE_PASSWORD=你的库密码 SIGN_KEY_ALIAS=turboims SIGN_KEY_PASSWORD=你的私钥密码

Step 3：注意路径写法——storeFile走的是相对/绝对文件解析，建议填绝对路径，避免工作目录切换导致找不到 keystore。

Step 4：验证—— 直接执行下一章的编译命令，若签名配置有误，报错会明确指向signingConfigs.sign。

五、编译 APK：Debug 与 Release 的差异 ⚙️

5.1 快速产出 Debug 包

./gradlew :app:assembleDebug

产物位于app/build/outputs/apk/debug/app-debug.apk。Debug 版不混淆、不压缩资源，versionName 后缀形如.d1234.abc12345（d+ 提交数 + 短哈希）。

5.2 构建 Release 包

./gradlew :app:assembleRelease

Release 版开启R8 混淆 + 资源压缩，混淆规则见 app/proguard-rules.pro（保留四大组件、Parcelable、Serializable 等经典规则），产物位于app/build/outputs/apk/release/。

📌 两个 buildType 都强制使用sign签名配置（见 app/build.gradle.kts），所以未配置签名信息时任何构建都会失败——这正是第四章要提前配好的原因。

六、adb 部署：安装上机与快速验证 📲

adb install -r app/build/outputs/apk/debug/app-debug.apk

• -r表示覆盖安装（保留数据），日常自测最常用
• 签名冲突处理：若设备装过正式包或其他签名构建，会报INSTALL_FAILED_UPDATE_INCOMPATIBLE，先执行adb uninstall io.github.vvb2060.ims.mod再安装即可
• 首次启动需按提示授权Shizuku（需设备已启动 Shizuku 服务），这是 App 获取提权能力的入口
• 运行异常时可用adb logcat抓取日志；App 内也内置了 LogcatActivity 日志查看页，方便直接截图排障

参考真机上的功能界面预览，可查看仓库中的 docs/Screenshot1.png 与 docs/Screenshot2.png。

七、常见构建报错速查表

总结

从零构建 Carrier IMS for Pixel 的完整链路可以浓缩为四步：git 克隆 → 配置local.properties签名 →./gradlew assembleDebug→adb install。掌握 settings.gradle.kts、gradle/libs.versions.toml、app/build.gradle.kts 与 signing.gradle 这四个文件，你就拥有了修改版本、换签名、出发布包的完整能力。后续若想让构建产物携带自己的渠道参数（如广告与商务合作接口地址），buildConfigField+ 环境变量覆盖机制（app/build.gradle.kts）也是很好的扩展起点。更多项目背景与功能设计可参阅 README.md 及docs/plans/下的设计文档。