使用华为云码道 CodeArts 从零开发 ReadFlow：TXT 分章、续读与 Android 跨端阅读器实战

轻阅读demo · Capacitor Android 打包指南

本项目是纯静态 Web 应用（原生 HTML/CSS/JS，无框架、无打包器），使用 Capacitor 6+ 封装为 Android APK。根目录结构保持原样，www/ 是 Capacitor 的 Web 资源目录（由脚本自动生成，勿手动改）。

xunlei_test/
├── index.html            ← Web 开发源（Live Server 直接调试）
├── css/  js/  lib/       ← 源资源（相对路径，适配 Capacitor）
├── scripts/copy-web.mjs  ← 同步脚本：根目录 → www/
├── www/                  ← 构建产物（npm run build 生成，已 .gitignore）
├── android/              ← Android 工程（npx cap add android 生成）
├── capacitor.config.json
└── package.json

0. 前置要求

工具	版本要求	说明
Node.js + npm	≥ 18	本机当前未安装，需先安装：https://nodejs.org
Android Studio	最新（含 JDK 17+ 与 Android SDK）	用于打开 `android/` 构建 APK
Java	构建走 Android Studio 自带 JDK，系统 Java 版本无关紧要

校验：node -v && npm -v

1. 一次性初始化

# 安装 Capacitor 依赖（@capacitor/core / cli / android）
npm install

# 添加 Android 平台（生成 android/ 工程，含 debug.keystore）
npx cap add android

npm run build 会先把根目录 index.html / css / js / lib 同步到 www/； cap add android 只需要一次。

2. 日常构建 / 同步 / 打包

# ① 同步 Web 资源到 www/（每次改完 Web 代码执行）
npm run build

# ② 推送到 Android 工程（把 www/ 复制进 android/app/src/main/assets/public）
npx cap sync

# 一步到位：build + sync
npm run sync

# ③ 打开 Android Studio（真机调试 / 构建 APK）
npm run open:android

一键打包 APK（debug 签名，Android Studio 同步完成且配置好 SDK 后）：

npm run apk:debug      # 等价：sync 后执行 gradlew assembleDebug
npm run apk:release    # 等价：sync 后执行 gradlew assembleRelease（需先配置正式签名，见 §4）

产物路径：

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

3. 真机调试

手机开启「开发者选项 + USB 调试」，连接电脑。
npm run open:android 打开工程 → 点 Run ▶ 部署到真机。
WebView 调试：Chrome 地址栏输入 chrome://inspect，可像网页一样审查 DOM / Console。（capacitor.config.json 中 webContentsDebuggingEnabled: true 已开启；正式发布前建议改回 false）

4. 签名配置

Debug（测试用）：Capacitor 生成的 android/app/debug.keystore 已内置，assembleDebug 直接产出可安装的 debug 签名 APK，无需额外配置。
Release（正式发布）：
1. 生成正式 keystore：
```
keytool -genkeypair -v -keystore release.keystore -alias xunlei -keyalg RSA -keysize 2048 -validity 10000
```
2. 在 android/app/build.gradle 的 signingConfigs 中配置 keystore 路径 / alias / 密码，并把 buildTypes.release.signingConfig 指向它。
3. npm run apk:release。

密钥文件请勿提交到 git（已在 .gitignore 排除 *.keystore）。

5. 存储兼容性（localStorage / IndexedDB）

当前实现：

元数据：localStorage（xl_books_v2 / xl_ai_key / xl_font / xl_theme）。
正文/缓存：原生 IndexedDB（js/db.js 自封装 dbSet/dbGet/dbDelete，不是 LocalForage）。

在 Capacitor Android WebView（Chrome 内核，页面运行于 https://localhost）中两者均原生可用，与浏览器行为一致。js/db.js 已加入一段尽力而为的持久化加固：

if (navigator.storage && navigator.storage.persist) {
  navigator.storage.persist().catch(() => {});
}

降级 / 排障方案（若个别机型数据丢失）：

优先调用 navigator.storage.persist()（已加），降低系统回收风险。
若 IndexedDB 打开失败（极少数隐私模式/空间不足），可加内存兜底：dbGet 失败时返回 null 并提示重新导入即可，不会崩溃（现有代码已按“取不到就报错提示”处理）。
大文件（MB 级正文）可迁移到官方插件 @capacitor/filesystem 或 @capacitor/preferences，本 demo 暂不引入，保持零插件依赖。

注意：卸载 App 或「清除数据」会清空 localStorage 与 IndexedDB（属系统行为，非本应用问题）。

6. 修改 Web 代码后的同步工作流

① 在根目录编辑 index.html / css / js（Live Server 或任意静态服务器实时预览）
        ↓
② npm run build          （根目录 → www/）
        ↓
③ npx cap sync           （www/ → android/app/src/main/assets/public）
        ↓
④ Android Studio 运行 / npm run apk:debug   （重新打包）

Web 端调试与 Android 端互不干扰：日常改 UI 用 Live Server 秒级刷新；需要验证 APK 时再 build + sync 即可，无需手动拷贝任何文件。