EasyAppShell/README.md

📱 EasyAppShell

一个极简的配置化 Android WebView 壳项目。

把你任何移动端 Web 项目打包成一个真正的 Android App —— 改改 URL、换个图标、改个名字，重新编译就是一个全新的 App。

---

✨ 特性

• 纯 WebView 壳 — 体积小、速度快，只有一个 Activity
• 配置驱动 — 所有设置都在 config.json 里，改配置 = 改 App
• 一键打包 — auto_package.py + 改 URL、改名字、换图标一步到位
• JS↔Native 桥接 — 前端可以调 Toast、分享、剪贴板等原生能力
• 完整 WebView 功能 — JavaScript、DOM 存储、定位、下拉刷新、进度条
• 自适应图标 — 支持 Android 8+ 自适应图标
• 安全配置 — 默认仅 HTTPS，支持白名单/黑名单

---

🚀 一分钟快速开始

前置条件

工具	说明
Java 17+	JDK，用于编译 Android 代码
Android SDK	编译 Android App 所需
Python 3.6+	运行自动打包脚本
Pillow (可选)	pip install Pillow，用于自动处理图标

设置 Android SDK 环境变量（根据你安装的路径）:

# Windows
set ANDROID_HOME=C:\Users\你的用户名\AppData\Local\Android\Sdk

# macOS / Linux
export ANDROID_HOME=~/Library/Android/sdk

没有 Android SDK？ 安装 Android Studio，打开 SDK Manager 安装 SDK 35。

打包你的第一个 App

# 1. 进入项目目录
cd EasyAppShell

# 2. 一键打包（改 URL + 名称 + 图标）
python auto_package.py \
    --url https://你的网站.com \
    --name "我的第一个 App" \
    --icon /path/to/icon.png

# 3. 在 dist/ 目录下找到 APK，安装到手机！

仅改配置不构建

python auto_package.py --url https://你的网站.com --name "测试版" --no-build
# 然后手动:
./gradlew assembleDebug

---

📖 完整参数说明

auto_package.py

参数	必填	说明
--url	✅	WebView 加载的主 URL
--name	✅	App 显示名称
--icon	❌	图标文件路径 (PNG/JPEG, 建议 1024×1024)
--package	❌	Android 包名 (默认: com.easyappshell.{name})
--output	❌	APK 输出目录 (默认: dist/)
--http	❌	允许 HTTP 混合内容
--portrait	❌	锁定竖屏
--landscape	❌	锁定横屏
--version	❌	App 版本号 (默认: 1.0.0)
--build	❌	Build 编号 (默认: 1)
--release	❌	构建 Release 版（需要签名）
--keystore	❌	Keystore 文件路径
--keystore-pass	❌	Keystore 密码
--key-alias	❌	Key 别名
--key-pass	❌	Key 密码
--no-build	❌	只生成配置文件，不构建

示例

# 最简用法
python auto_package.py --url https://mytool.com --name "我的工具"

# 带自定义图标、锁定竖屏
python auto_package.py --url https://shop.com --name "商城" \
    --icon ~/icons/shop.png --portrait

# Release 构建（需签名）
python auto_package.py --url https://app.com --name "正式版" \
    --release --keystore release.keystore --keystore-pass 123456 --key-alias mykey

# 多个 App 共存（不同包名）
python auto_package.py --url https://app1.com --name "应用一" --package com.example.app1
python auto_package.py --url https://app2.com --name "应用二" --package com.example.app2

---

⚙️ 手动配置（config.json）

你也可以直接编辑 app/src/main/assets/config.json 来精细调控：

{
  "app_name": "EasyAppShell",
  "main_url": "https://example.com",
  "enable_js": true,
  "enable_dom_storage": true,
  "status_bar_color": "#2196F3",
  "enable_swipe_refresh": true,
  "orientation": "unspecified",
  "allowed_origin_whitelist": ["*"],
  "blocked_hosts": [],
  "extra_http_headers": {}
}

全部配置项说明见文件内的注释。

---

🌐 JS → Native 桥接

前端页面可以通过 window.NativeBridge 调用原生功能：

// 弹出 Toast
window.NativeBridge.showToast("操作成功");

// 分享链接
window.NativeBridge.shareUrl("标题", "https://example.com");

// 复制到剪贴板
window.NativeBridge.copyToClipboard("要复制的内容");

// 获取 App 版本
var version = window.NativeBridge.getAppVersion();

此功能可在 config.json 中关闭："allow_javascript_interface": false

---

🏗 项目结构

EasyAppShell/
├── auto_package.py              # ★ 一键打包脚本
├── app/
│   ├── build.gradle.kts         # App 构建配置
│   └── src/main/
│       ├── assets/
│       │   ├── config.json      # ★ 核心配置文件
│       │   └── error.html       # 网络错误页
│       ├── java/.../
│       │   ├── MainActivity.kt  # 主 Activity
│       │   ├── WebAppConfig.kt  # 配置解析
│       │   └── NativeBridge.kt  # JS↔Native 桥接
│       ├── res/                 # 资源文件
│       └── AndroidManifest.xml  # 清单文件
├── build.gradle.kts             # 顶层构建
├── settings.gradle.kts
└── gradlew / gradlew.bat        # Gradle Wrapper

---

❓ 常见问题

Q: 打包出来的 APK 有多大？ A: Debug 版约 3-5MB，Release 版约 2-3MB（经过 ProGuard 压缩）。

Q: 如何生成 Release 签名？ A: 使用 Android Studio 或 keytool 生成 keystore：

keytool -genkey -v -keystore my-release-key.keystore \
  -alias my-key-alias -keyalg RSA -keysize 2048 -validity 10000

Q: 可以支持多个页面/导航吗？ A: 这是个 WebView 壳，路由交给你的 Web 项目处理。WebView 支持返回键后退。

Q: 为什么安装后 App 名称还是 EasyAppShell？ A: 你可能遗漏了 --name 参数，或需要重新运行打包脚本。

Q: 我修改了 config.json 但构建后没生效？ A: 检查 assets/config.json 的路径是否正确，然后 clean 再构建：

./gradlew clean assembleDebug

---

📄 License

MIT