freeapp（玄鲸 / Whale-LLT）是一个本地优先的 AI 聊天陪伴应用，基于 Web 技术开发，并通过Capacitor打包为 Android APK。本文面向新手，带你完整走通 freeapp 的 Capacitor 打包部署流程：从环境准备、npx cap sync同步代码，到刘海屏安全区适配、本地通知权限配置和 App 图标设置，一篇看懂 Web 应用如何变成真正的安卓应用。

为什么要把 freeapp 打包成 Android APK？

网页版（浏览器直接打开 www/index.html）虽然零部署即用，但原生 APK 能解锁三类浏览器给不了的能力：

💡 这些能力分别由 www/utils/notificationManager.js、www/utils/dataMigrator.js 和 www/style.css 中的安全区样式实现。

30秒看懂：freeapp 的 Capacitor 项目结构

freeapp 仓库是典型的「Capacitor + 静态 Web」结构，记住三个关键目录即可：

freeapp/ ├── www/ # Web 应用主体（HTML/JS/CSS），Capacitor 打包的"源材料" │ ├── index.html # Web 应用主入口 │ ├── script.js # 主要前端脚本 │ ├── style.css # 样式（含安全区适配） │ ├── capacitor.js # Capacitor 插件桥接初始化 │ └── utils/ # 通知、数据迁移、记忆表等工具模块 ├── android/ # Capacitor 生成的 Android 原生工程 │ └── app/src/main/ # AndroidManifest、MainActivity、图标、Splash ├── capacitor.config.json # Capacitor 核心配置 └── package.json # npm 依赖（Capacitor 插件清单）

核心配置只有 5 行，见 capacitor.config.json：

• appId：com.whale.llt，即 APK 的安卓包名；
• appName：应用显示名称；
• webDir：www，同步时该目录内容会被整体复制到安卓工程中。

package.json 中声明了本项目用到的 Capacitor 插件：@capacitor/filesystem（文件读写）、@capacitor/local-notifications（本地通知）、@capawesome/capacitor-file-picker（文件选择器）。

环境准备：打包 freeapp APK 的工具清单

开始之前，请确认电脑上已安装以下四项（缺一不可）：

1. Node.js 和 npm—— 运行npx cap系列命令；
2. Android Studio—— 打开原生工程、构建 APK；
3. JDK 17 或更高版本—— 编译运行所需；
4. Android SDK—— 随 Android Studio 一并安装即可。

获取源码：

git clone https://gitcode.com/gh_mirrors/fr/freeapp cd freeapp npm install

4 步从 Web 代码到 APK：最快打包方法

第 1 步：安装依赖

npm install

第 2 步：同步 Web 代码到安卓工程

这是新手最容易遗漏的一步。Capacitor 会把 capacitor.config.json 中webDir指向的www/目录复制到android/工程里：

npx cap sync

⚠️ 之后每次修改 Web 代码，都必须重新执行npx cap sync，否则 APK 里永远是旧页面。

第 3 步：用 Android Studio 打开工程

npx cap open android

等待 Gradle 同步完成。安卓工程的最低/目标 SDK 定义在 android/variables.gradle（minSdk 23/targetSdk 35，覆盖 Android 6.0 到 15）。

第 4 步：构建 APK

在 Android Studio 菜单中选择Build → Build Bundle(s) / APK(s) → Build APK(s)，构建完成后点击右下角的locate链接，APK 位于：

android/app/build/outputs/apk/debug/app-debug.apk

将 APK 传到手机安装（需允许"安装未知来源的应用"）即可。调试期产物在 android/app/release/output-metadata.json 同级目录下管理。

刘海屏和底部导航栏：freeapp 安全区适配怎么做？

全面屏时代，状态栏和导航栏会压住网页内容。freeapp 用了「原生透明栏 + CSS 安全区」的组合拳：

① 原生层：让状态栏"透"过来

android/app/src/main/res/values/styles.xml 中的AppTheme.NoActionBarLaunch主题去除了 ActionBar，配合AppTheme.NoActionBar的透明背景，使 WebView 内容可以延伸到状态栏之下。

② CSS 层：用env(safe-area-inset-top)自动让位

在 www/style.css 中，标题栏、二级菜单和侧边栏头部都做了刘海屏适配：

.main-header { padding-top: env(safe-area-inset-top); /* 顶部让出刘海/挖孔高度 */ } .sidebar-header { padding-top: calc(20px + env(safe-area-inset-top)); }

env(safe-area-inset-top)是浏览器/WebView 提供的动态值：普通手机上是 0，刘海屏/挖孔屏上自动变成刘海高度，一份 CSS 适配所有机型，无需写死像素。

📱 建议：即便做了适配，仍应在刘海屏、挖孔屏、三键/手势导航栏等不同设备上实测一轮（见 README.md 的注意事项）。

本地通知：让 freeapp 拥有系统级消息提醒

APK 版的一大亮点是本地通知（比如"AI 角色给你发了条新消息"），实现分三层：

① 权限声明—— android/app/src/main/AndroidManifest.xml：

• POST_NOTIFICATIONS：Android 13+ 的通知发送权限；
• SCHEDULE_EXACT_ALARM：支持定时精确通知。

② 启动时主动请求权限—— MainActivity.java 在onCreate中检查并请求通知权限（同时处理麦克风权限），避免 Capacitor 插件"有权限声明却拿不到授权"的尴尬。

③ Web 端封装—— www/utils/notificationManager.js 将插件调用封装成window.notificationManager，先检查环境是否为 Capacitor、再走checkPermissions → requestPermissions流程，之后调用scheduleNotification({ title, body, id, schedule })即可发送通知；www/capacitor.js 则统一导出Filesystem、FilePicker、LocalNotifications三个插件供 Web 代码使用。

使用侧只需要：

window.sendNotification('新消息', 'AI 角色给你发来了消息');

🔔 首次使用通知和文件功能时，系统会弹出权限请求，请点"允许"。

设置 App 图标与收尾细节

仓库自带 icon.png 作为图标源文件（1024×1024）。

更换图标的完整步骤请照做 app-icon-guide.md：

1. npx cap open android打开工程；
2. 右键app文件夹 →New → Image Asset；
3. Icon Type 保持Launcher Icons (Adaptive & Legacy)，选择图标图片，可调 Resize 滑块；
4. 在 Background Layer 设置背景色，Finish 后同步工程；
5. 重新 Build APK。

各分辨率的启动图（Splash）分布在 android/app/src/main/res/drawable-port-xxhdpi/ 等drawable-port-*、drawable-land-*目录，横竖屏均已覆盖。

常见问题：打包部署排错速查

完整排错流程见 README.md 的"问题排查"章节。

小结

freeapp 的 Capacitor 打包链路可以浓缩为一条命令链：

npm install && npx cap sync && npx cap open android

配合 Android Studio 的 Build APK，即可获得一个具备安全区适配、本地通知、文件导入导出能力的安卓应用。这套「静态 Web + Capacitor 桥接」的模式轻量、易维护，也非常适合作为新手学习跨平台打包的入门案例。