Super Productivity Android 构建指南Connectivity-Free 与 Online-Only 双模式配置实战【免费下载链接】super-productivitySuper Productivity is an advanced todo list app with integrated Timeboxing and time tracking capabilities. It also comes with integrations for Jira, GitLab, GitHub and Open Project.项目地址: https://gitcode.com/GitHub_Trending/su/super-productivity导读Super Productivity 的 Android 客户端位于仓库的android/目录官方推荐流程是先克隆整个super-productivity仓库而非单独克隆 Android 仓库随后借助根目录的 npm 脚本完成前端编译、Capacitor 同步与 Gradle 打包。本文以 docs/wiki/2.14-Build-for-Android.md 为骨架完整讲解LAUNCH_MODE启动模式配置、Connectivity-Free离线优先与 Online-Only兼容两种模式的构建与安装步骤并结合app_config.properties、config.gradle与LaunchDecider.kt源码说明配置项在编译期与运行期的真实作用。读完后你将能独立产出可安装的 Debug/Release APK并按需切换离线、生产、本地开发或自托管服务器四种运行目标。一、两种启动模式离线优先与在线兼容Android 应用支持两种启动模式这是整个构建与配置体系的核心概念Connectivity-Free Mode推荐无需任何网络连接即可使用应用核心功能仍可配合 WebDAV、Dropbox 进行同步也可完全离线使用。它是基于 Capacitor 的新架构对应CapacitorMainActivity。Online-Only ModeCompatibility Mode传统 WebView 架构FullscreenActivity需要连接生产服务器、本地开发服务器或自托管服务器才能运行。两种模式的差异与选择策略在 android/README.md 中有完整说明。从源码看Online-Only 模式的入口 FullscreenActivity.kt 会加载${BuildConfig.ONLINE_SERVICE_PROTOCOL}://${BuildConfig.ONLINE_SERVICE_HOST}指向的 URL而 Connectivity-Free 模式则由 Capacitor 打包离线前端资源运行。二、LAUNCH_MODE配置详解启动模式由 android/app/app_config.properties 文件中的LAUNCH_MODE决定。该文件位于android/目录即android/app/app_config.properties仅用于本地修改取值含义0默认行为读取 SharedPreferences 自动决策1强制 Online-Only Mode兼容模式2强制 Connectivity-Free Mode推荐LAUNCH_MODE2重要app_config.properties仅供本地修改除非你完全清楚自己在做什么否则不要提交commit该文件。这一点在 android/README.md 与 android/README_OFFLINE.md 中反复强调。配置项在编译期如何生效LAUNCH_MODE并非运行期动态读取而是在Gradle 编译期被固化进BuildConfig。参见 android/app/config.gradleGradle 启动时读取android/app/app_config.properties若文件存在则加载为Properties通过getProperty(LAUNCH_MODE, 0)读取配置缺省值为0连同其余三个配置项一起生成BuildConfig.LAUNCH_MODE等字段字符串形式供 Kotlin 源码使用。因此修改配置文件后必须重新执行构建才会生效直接运行已安装的旧 APK 不会感知配置变化。运行期的决策逻辑BuildConfig.LAUNCH_MODE传入 LaunchDecider.kt 的getLaunchMode()值为1→ 强制MODE_ONLINE旧FullscreenActivity值为2→ 强制MODE_OFFLINE新CapacitorMainActivity值为0或无法解析 → 读取 SharedPreferences 中的launch_mode由determineLaunchMode()自动决策。自动决策逻辑LaunchDecider.kt 与resolveDefaultLaunchMode如下全新安装firstInstallTime lastUpdateTime→ 直接进入MODE_OFFLINE避免任何联网尝试升级安装若SharedPreferences中已有非默认模式则沿用否则检查是否存在旧数据文件databases/SupKeyValStore存在则切到MODE_ONLINE保留旧体验不存在则进入MODE_OFFLINE。该决策结果会写回 SharedPreferences供后续启动复用也解释了为什么LAUNCH_MODE0是智能兼容而非简单的二选一。三、Connectivity-Free 模式构建推荐Connectivity-Free 模式无需额外配置LAUNCH_MODE0或2均可启用其中2保证新装即离线不会尝试连接在线服务而0可能读取 SharedPreferences 并在有网络时连接在线服务详见 android/README_OFFLINE.md。1. 克隆仓库并初始化子模块官方明确要求克隆整个super-productivity仓库确保包含 Android 子模块git clone https://github.com/super-productivity/super-productivity.git cd super-productivity git submodule init git submodule update2. 安装前端依赖需要 Node.js 与 npm在仓库根目录执行npm install3. 编译 Android 项目在仓库根目录执行而非android/目录内npm 脚本的定义见根目录 package.json# 测试staging构建生成 Debug APK npm run dist:android # 生产构建生成 Release APK npm run dist:android:prod以dist:android为例其内部执行链为buildFrontend:stageWeb:unminified→sync:androidCapacitor 同步→assemble:android:stage产物输出到android/app/build/outputs/apk/debug/dist:android:prod则先构建生产前端再执行assemble:android:prod产物输出到android/app/build/outputs/apk/release/。sync:android步骤依赖根目录的 capacitor.config.tswebDir: dist/browser、appId: com.super-productivity.app将编译后的前端产物同步进 Android 工程。4. 安装 APK方式一Android Studio打开 Android Studio选择Open an existing project定位到克隆仓库中的android目录其 settings.gradle 已通过include :app与capacitor.settings.gradle引入应用模块按提示构建并运行到设备或模拟器。方式二npm 脚本依赖 adb# 安装测试构建fdroid Debug APK npm run install:android # 安装生产构建fdroid Release APK npm run install:android:prod对应脚本见 package.json 的install:androidadb install -r android/app/build/outputs/apk/fdroid/debug/app-fdroid-debug.apk与install:android:prodadb install -r android/app/build/outputs/apk/fdroid/release/app-fdroid-release.apk。-r参数表示覆盖安装已存在的应用。四、Online-Only 模式配置与三种服务器目标若需要连接生产、本地开发或自托管服务器则将LAUNCH_MODE设为1强制或0升级用户默认并配合下列参数详见 android/README_ONLINE.md。完整参数清单与注释见 android/app/app_config.properties配置项默认值作用LAUNCH_MODE0启动模式0 默认 / 1 强制在线 / 2 强制离线ONLINE_SERVICE_IS_LOCALfalsetrue连本地开发服务器false连远程/生产/自托管ONLINE_SERVICE_HOSTapp.super-productivity.com服务器地址本地模式时忽略固定用10.0.2.2:4200ONLINE_SERVICE_PROTOCOLhttpshttp或https本地 Debug 构建默认http1. 使用生产服务器LAUNCH_MODE1 ONLINE_SERVICE_IS_LOCALfalse默认即指向https://app.super-productivity.com。2. 使用本地开发服务器LAUNCH_MODE1 ONLINE_SERVICE_IS_LOCALtrue先在开发机启动 Angular 开发服务器ng serve --disable-host-check --host 0.0.0.0 --port 4200 --live-reload --watchAndroid Studio 模拟器通过http://10.0.2.2:4200访问宿主机10.0.2.2是模拟器对宿主机的固定别名模拟器自带 Chrome 浏览器亦可直接访问该地址验证。3. 使用自托管服务器LAUNCH_MODE1 ONLINE_SERVICE_IS_LOCALfalse ONLINE_SERVICE_HOSTyour.server.address ONLINE_SERVICE_PROTOCOLhttps本地 vs 远程的编译期处理android/app/config.gradle 展示了ONLINE_SERVICE_IS_LOCAL的关键逻辑当其为true且为 Debug 构建时ONLINE_SERVICE_HOST强制替换为10.0.2.2:4200、协议强制为http否则才采用配置中的ONLINE_SERVICE_HOST/ONLINE_SERVICE_PROTOCOL。这正是 android/README_ONLINE.md 中切换服务器无需改动 Kotlin 源码的底层依据——所有地址最终通过BuildConfig注入而 FullscreenActivity.kt 组装 URL 并加载到 WebView。五、构建与配置注意事项配置文件仅限本地app_config.properties修改只应在本地进行切勿误提交到版本库以免影响其他开发者或 CI 构建。改配置必须重新构建配置在 Gradle 编译期固化进BuildConfig修改后需重新执行npm run dist:android或npm run dist:android:prod。新装推荐LAUNCH_MODE2避免任何在线连接尝试获得开箱即用的离线体验升级用户保持0则可自动按历史数据迁移。Debug 构建地址提示FullscreenActivity在 Debug 构建时会以 Toast 展示当前加载的 URLDEBUG: $appUrl便于确认 WebView 实际指向的服务器也方便通过chrome://inspect调试远程设备 WebView。六、相关文档android/README.mdAndroid 应用总览与启动模式说明android/README_OFFLINE.mdConnectivity-Free 模式详细构建步骤推荐android/README_ONLINE.mdOnline-Only 模式与三种服务器配置docs/wiki/2.12-Package-the-App.mdElectron/桌面端打包docs/wiki/2.11-Run-the-Development-Server.md本地开发服务器启动方式【免费下载链接】super-productivitySuper Productivity is an advanced todo list app with integrated Timeboxing and time tracking capabilities. It also comes with integrations for Jira, GitLab, GitHub and Open Project.项目地址: https://gitcode.com/GitHub_Trending/su/super-productivity创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考