shiahonb777--web-to-app
wehub-resource-sync
293 行
20 KiB
Markdown
293 行
20 KiB
Markdown
<!-- WEHUB_ZH_README -->
|
||
> [!NOTE]
|
||
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
|
||
> [English](./README.en.md) · [原始项目](https://github.com/shiahonb777/web-to-app) · [上游 README](https://github.com/shiahonb777/web-to-app/blob/HEAD/README.md)
|
||
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。
|
||
|
||
<div align="center">
|
||
|
||
<img src="app/src/main/res/mipmap-xxxhdpi/ic_launcher.png" width="96" alt="WebToApp icon" />
|
||
|
||
# WebToApp
|
||
|
||
### 在手机上直接从 Web 项目构建 Android APK。
|
||
|
||
**一款设备端 APK 工坊，远不止 URL 封装——它能 fork 并执行完整的服务器运行时、内置加固的反审查网络栈、为 Google Play 签名打包，并运行 MV3 浏览器扩展，全程无需 PC 或远程构建服务器。**
|
||
|
||
**English** · [简体中文](.github/docs/README_CN.md)
|
||
|
||
[](https://github.com/shiaho777/web-to-app/stargazers)
|
||
[](https://github.com/shiaho777/web-to-app/network/members)
|
||
[](LICENSE)
|
||
[](#)
|
||
|
||
</div>
|
||
|
||
<p align="center">
|
||
<a href="#what-makes-webtoapp-different">与众不同之处</a> ·
|
||
<a href="#what-you-can-build">可构建内容</a> ·
|
||
<a href="#capability-overview">能力概览</a> ·
|
||
<a href="#full-feature-map">功能地图</a> ·
|
||
<a href="#module-market">模块市场</a> ·
|
||
<a href="#architecture">架构</a> ·
|
||
<a href="#build-from-source">构建</a>
|
||
</p>
|
||
|
||
---
|
||
|
||
<div align="center">
|
||
<img src=".github/assets/social-preview.jpg" width="90%" alt="WebToApp: My Apps home, Create App picker, main toolbox, and per-app APK actions running on an Android phone" />
|
||
</div>
|
||
|
||
---
|
||
|
||
## What makes WebToApp different
|
||
|
||
大多数「网站转 App」工具止步于用 WebView 封装 URL。WebToApp 更接近口袋大小的 APK 工坊，其硬核差异正在于此：
|
||
|
||
- **在设备上运行真实的服务器运行时。** Node.js、PHP、Python、Go 和 WordPress 以原生二进制形式从应用存储中 fork+exec 执行——类似 Termux，但打包为可安装的 APK。URL 封装类工具完全做不到这一点。
|
||
- **内置加固的反审查网络栈。** DNS-over-HTTPS、TLS 指纹伪装（Chrome / Firefox / Safari JA3 模板）配合本地 MITM 桥接、GeckoView 引擎上的 Encrypted Client Hello（ECH）以加密 SNI、按应用代理，以及针对受限 SPA 的 CORS 绕过。
|
||
- **整个构建流程自包含。** 二进制 AXML/ARSC 修补、权限裁剪、V1/V2/V3 签名，以及 Google Play 就绪的 AAB 导出，均在应用内通过 `apksig` 完成——无需远程构建队列，无需 PC。
|
||
- **发布后仍可扩展。** 可添加 JS/CSS 模块、Tampermonkey 风格的 userscript，或 MV3 Chrome 扩展（从 Chrome Web Store 实时搜索并安装），无需重建宿主应用。
|
||
- **宿主 UI 开箱即支持 10 种语言。** 中文、English、阿拉伯语（RTL）、葡萄牙语、西班牙语、法语、德语、俄语、日语和韩语——可在设置中随时切换；应用内新增文案均维护全部十种语言。
|
||
|
||
---
|
||
|
||
## Capability overview
|
||
|
||
快速浏览内置能力。各项均链接至下方详细功能地图。
|
||
|
||
| Area | Highlights |
|
||
| --- | --- |
|
||
| **Build targets** | Web · HTML · Frontend · WordPress · Node.js · PHP · Python · Go · Image · Video · Gallery · Multi-Web |
|
||
| **Browser engines** | 默认系统 WebView；可选 GeckoView（Firefox）运行时以支持 ECH / SNI 加密 |
|
||
| **Network & anti-censorship** | DoH（7 家提供商）、TLS 指纹伪装 + MITM 桥接、ECH、静态/PAC/SOCKS5 代理、CORS 绕过 |
|
||
| **Privacy & hardening** | 50+ 向量浏览器指纹伪装、资源加密（AES-256-GCM）、反调试、激活码门控 |
|
||
| **Local runtimes** | 原生 Node.js 18.20、PHP 8.4 + Composer 2.10、Python 3.14、官方 Go 1.26、基于 SQLite 的 WordPress 7.x |
|
||
| **Extensions** | 内置模块、搭配 `GM_*` 的 userscript、MV3 Chrome 扩展、Chrome Web Store 实时搜索 |
|
||
| **APK/AAB output** | 设备端 V1/V2/V3 签名、带 targetSdk 重写的 Google Play AAB 导出、keystore 管理 |
|
||
| **AI coding** | 提示词驱动生成 Web 应用、模块、userscript 和运行时项目；429/5xx 自动重试 |
|
||
| **Host languages** | **10 种 UI 语言** — 中文 · English · العربية · Português · Español · Français · Deutsch · Русский · 日本語 · 한국어（阿拉伯语 RTL） |
|
||
|
||
---
|
||
|
||
## What you can build
|
||
|
||
| Input | Output | Good for |
|
||
| --- | --- | --- |
|
||
| Website URL | 基于 WebView 的 APK | 落地页、工具、仪表盘、文档、内部系统 |
|
||
| HTML / static front-end | 由 localhost 支撑的 APK | React、Vue、Vite、静态构建、离线 Web 应用 |
|
||
| Node.js / PHP / Python / Go | 内置设备端本地服务器的 APK | 小型服务端应用、管理工具、演示、原型 |
|
||
| WordPress | 通过本地 PHP + SQLite 运行 WordPress 的 APK | 便携站点、主题/插件演示、内容包 |
|
||
| Images / video / galleries | 以媒体为主的 APK | 相册、课程资料、作品集、离线查看器 |
|
||
| Multiple sites | 标签页/卡片/信息流/抽屉式多站 APK | 链接枢纽、门户、应用合集 |
|
||
| Installed APK | 换标克隆或快捷方式伪装 | 图标/名称/包名实验、重打包研究 |
|
||
|
||
---
|
||
|
||
## Full feature map
|
||
|
||
WebToApp 拥有大量开关。以下按用例分组，并保持可折叠，以便页面顶部易于浏览。
|
||
|
||
<details>
|
||
<summary><b>🌐 Browser engine & networking</b></summary>
|
||
|
||
- **双引擎** — 默认系统 WebView，或首次使用时下载的可选 GeckoView（Firefox）运行时。
|
||
- **内核风格伪装** — 在保留真实引擎的同时，可呈现为 Chrome、Edge、Samsung Internet、Firefox 或 Safari 风格。
|
||
- **桌面模式**、自定义 User-Agent，以及在 document-start / end / idle 时注入 JS/CSS。
|
||
- **弹窗处理** — 同窗口、外部浏览器、弹窗窗口或拦截。
|
||
- **代理** — 静态 HTTP/HTTPS/SOCKS5、PAC、身份验证、绕过规则，以及本地 HTTP-to-SOCKS 桥接。
|
||
- **DNS-over-HTTPS** — Cloudflare、Google、AdGuard、NextDNS、CleanBrowsing、Quad9、Mullvad，以及自定义端点；严格或自动模式。
|
||
- **Encrypted Client Hello（ECH）** — 在 TLS 握手中加密 SNI（仅 GeckoView；开启时自动接入 DoH + GeckoView）。
|
||
- **TLS 指纹伪装** — 模拟 Chrome 131 / Firefox 133 / Safari 18 JA3 配置（或自定义密码套件），通过本地 TLS-MITM 桥接，使发出的 ClientHello 与真实浏览器一致。
|
||
- **CORS 绕过** — 默认开启，供调用被 CORS 拦截的外部 API 的静态 SPA 使用；同源流量不受影响，仅需 CORS 的应用可使用轻量 `PrivateNetworkNativeBridgeAdapter`，无需完整 Native Bridge 表面。
|
||
- **故障转移** — 主目标不可达时自动回退到镜像 URL。
|
||
- **PWA** 离线缓存策略、自定义错误页、按应用主机覆盖，以及支付 scheme 处理器。
|
||
- **兼容性开关** — blob 下载拦截、滚动记忆、图片修复、剪贴板 / 方向 / 通知 polyfill、私有网络桥接，以及 Native Bridge 能力门控。
|
||
- **下载位置** — 系统 Downloads、应用私有存储，或用户选择的 SAF 文件夹，经完整打包透传链接入。
|
||
|
||
</details>
|
||
|
||
<details>
|
||
<summary><b>🛡️ Privacy, fingerprint defense & hardening</b></summary>
|
||
|
||
- **50+ 向量的浏览器指纹伪装** — User-Agent、WebGL、Canvas、AudioContext、ClientRects、时区、语言、内存、媒体设备、WebRTC、字体、电池、权限、性能、存储、通知、CSS media、iframe 传播，以及错误栈清理。
|
||
- **Hosts 规则广告拦截器**，配合 cosmetic MutationObserver 过滤、**20 个内置社区过滤列表**（EasyList、uBlock Origin、AdGuard、AdAway，以及 8 个语言专属列表）、按来源启用/禁用/删除，以及打包进 APK 的自定义订阅规则。
|
||
- **资源加密**（PBKDF2 + AES-256-GCM），用于打包配置、HTML、媒体和 BGM；可选自定义加密密码，强度高于由包名/证书派生的密钥。
|
||
- **启用加密时的运行时加固** — 反调试、反 Frida、DEX 篡改检测；威胁响应为仅记录日志、静默退出或随机崩溃。
|
||
- **WebView/内容隔离**，覆盖存储、WebRTC、Canvas、Audio、WebGL、字体、请求头与 IP 表面。
|
||
- **激活码门控** — 本地校验，或使用 EC P-256 签名的自有 HTTPS 端点。详见[远程激活文档](.github/docs/remote-activation.md)。
|
||
|
||
</details>
|
||
|
||
</details>
|
||
|
||
<details>
|
||
<summary><b>📦 本地服务端运行时（设备上 fork + exec）</b></summary>
|
||
|
||
- **Node.js**（18.20.x）通过原生 `node_launcher` 包装器加载 `libnode.so`，在专用 `:nodejs` OS 进程中运行；支持自定义原生 `.node` 扩展。
|
||
- **PHP 8.4** 来自 `pmmp/PHP-Binaries`，首次使用时下载一次，附带 Composer 2.10.x 及自定义原生扩展（`zend_extension`、`.so`）。
|
||
- **Python 3.14** — 支持 Flask、Django、通过 uvicorn 运行 FastAPI、Tornado 及内置 HTTP 服务器；pip 依赖解析至 `.pypackages`，支持自定义原生扩展；二进制名称带版本号，后续升级不会硬编码路径。
|
||
- **Go 1.26** — 官方 Linux arm64 工具链（`.tar.gz` 来自 `dl.google.com`，中国区使用 USTC 镜像），设备端 `go build` / `go mod` / `go run`、`vendor/` 离线构建、静态文件服务，以及原生 `go_exec_loader` 包装器；DNS 与 CA 信任均经由与 PHP 相同的本地 JVM 桥接。
|
||
- **WordPress 7.x** 基于本地 PHP + SQLite（`sqlite-database-integration`），支持主题与插件导入。
|
||
- **Linux Environment** 界面管理 Node、PHP 与 Python 的工具链及依赖。
|
||
- **Port Manager** 通过广播接收器协调各生成应用的运行时端口。
|
||
- **本地 DNS 桥接代理**（Android JVM 中的 HTTP CONNECT）为运行时提供可用的 DNS 解析与出站 HTTP，解决 musl/打包二进制无法访问系统解析器的问题。
|
||
|
||
</details>
|
||
|
||
<details>
|
||
<summary><b>🧩 扩展与自动化</b></summary>
|
||
|
||
- **内置模块** — 视频下载（YouTube / Bilibili / 抖音 / 小红书提取器）、带 YouTube 增强的视频增强器（跳过广告、最高画质、后台播放、SponsorBlock）、网页分析器、页内查找、深色模式、隐私工具、内容增强器、元素屏蔽器，以及 YouTube 启动器。
|
||
- **Userscripts** — Greasemonkey/Tampermonkey 风格的 `.user.js`，配有 `GM_*` 桥接（存储、请求、样式、菜单命令）及基于 Promise 的 `GM.*` API，由脚本授权（grants）控制。
|
||
- **MV3 Chrome 扩展运行时**，用于在隔离或主世界（main world）中运行 manifest 内容脚本，并为 runtime、storage、tabs、scripting 及声明式网络请求解析提供 `chrome.*` polyfill。
|
||
- **应用内 Chrome Web Store 搜索** — 按关键词浏览并安装浏览器扩展（或粘贴商店 URL / 扩展 ID），离线时可回退至手动导入。
|
||
- **导出码**（`WTA1:` gzip + Base64）及通过 ZXing 的二维码分享。
|
||
- **AI Coding** 技能可生成模块、userscripts、MV3 扩展、前端应用及本地运行时项目，对 429/5xx 自动重试/退避，plan 模式退出时等待用户确认。
|
||
|
||
</details>
|
||
|
||
<details>
|
||
<summary><b>📱 应用体验</b></summary>
|
||
|
||
- **启动页** — 图片或视频，支持跳过行为、裁剪区间及固定方向。
|
||
- **背景音乐** — 带同步 LRC 歌词的播放列表、歌词动画、自定义字体/颜色/描边/阴影，以及在线音乐搜索。
|
||
- **工具栏、状态栏（浅色与深色）、导航、悬浮窗模式及长按菜单样式。** 状态栏颜色可跟随主题、自定义颜色、完全透明，或 **PAGE_TOP**（采样页面顶部像素，使界面 chrome 与内容一致）。
|
||
- **下载位置模式** — 系统 Downloads、应用私有目录，或用户选择的自定义 SAF 文件夹。
|
||
- **公告模板**，用于启动、定时间隔及无网络场景。
|
||
- **宿主应用语言** — 在 10 种语言间切换整个构建器 UI（中文 / English / العربية / Português / Español / Français / Deutsch / Русский / 日本語 / 한국어）；阿拉伯语完整支持 RTL。
|
||
- **翻译浮层** — 通过 Google、MyMemory、LibreTranslate、Lingva 或 Auto 引擎支持 20 种目标语言（对生成应用的*内容*进行页内翻译，与宿主 UI 语言相互独立）。
|
||
- **打印桥接** — 拦截 `window.print()` 及 blob/data-URL PDF，接入 Android 打印框架 / PDF 导出（含 onPageStarted 重新注入回退，确保较晚的导航仍被挂钩）。
|
||
- **通知** — Web Notification polyfill、带进度的定时与持久通知、URL 轮询前台服务、深度链接、开机自启、定时启动及后台运行服务。
|
||
- **按应用使用统计**，含 Vico 图表与 URL 健康监测。
|
||
|
||
</details>
|
||
|
||
<details>
|
||
<summary><b>🔧 APK / AAB 导出与签名</b></summary>
|
||
|
||
- **自定义包名**、`versionName`、`versionCode`、图标、标签、架构目标及导出格式。
|
||
- **构建时权限注入**，未使用的权限会从模板 manifest 中剔除。
|
||
- **一键 AAB 导出** — 按需自动构建 APK，转换为 Play 就绪的已签名 AAB，`targetSdk` 重写为 Play 要求的级别（当前为 35），并在本地生成 protobuf 元数据；构建过程中可取消。
|
||
- **Keystore 管理** — 创建、导入、导出、删除及查看证书指纹；支持 PKCS12/PFX/JKS/BKS 导入，包括 Android Studio 上传密钥场景（store 与 key 密码不同）。
|
||
- **签名方案** — V1、V2、V3 可独立控制，旧版证书自动回退；可为 `META-INF/<name>.SF` / `.RSA` 自定义 V1 签名器文件名。
|
||
- **性能选项** — 图片压缩、WebP 转换、代码压缩、懒加载、DNS 预取及 preload 提示。
|
||
- **完整项目与应用数据备份/恢复。**
|
||
|
||
</details>
|
||
|
||
<details>
|
||
<summary><b>🗂 文件管理与项目工具</b></summary>
|
||
|
||
- **文件管理器** — 单屏查看、分享、安装、打开及清理构建产物（APK 构建、AAB 导出、应用克隆、构建日志）与用户文件目录，附带只读构建日志查看器。
|
||
- **网站抓取器**，用于离线包 — HTML、CSS、JS、图片、字体、`url()`、`srcset`、`@import`、路径重写、同域限制、深度限制及大小限制；并行流式 worker 池，主线程进度回调。
|
||
- **多 Web 布局** — 标签页、卡片、信息流、抽屉，各站点图标/主题色/提取选择器/刷新间隔，以及共享 JS/CSS。
|
||
- **图库应用** — 分类媒体、网格/列表/时间线视图、随机/单曲循环、排序、缩略图栏、浮层、自动下一首及播放记忆。
|
||
- **App Modifier** — 快捷方式伪装或真实二进制克隆，含 manifest/资源修补与重新签名。
|
||
|
||
</details>
|
||
|
||
<details>
|
||
<summary><b>🔬 专用工具与研究功能</b></summary>
|
||
|
||
- **Forced-run**、**BlackTech**、**device disguise** 与 **Icon Storm** 仅供技术演示，且必须在用户知情同意后方可使用。
|
||
|
||
</details>
|
||
|
||
---
|
||
|
||
## 模块市场
|
||
|
||
WebToApp 拥有基于 GitHub 的模块市场，供社区贡献 JS/CSS 扩展模块。目录即本仓库中的文件，贡献流程与普通 pull request 相同。
|
||
|
||
```
|
||
modules/
|
||
├── registry.json # app-facing catalog
|
||
├── submissions.json # CI-generated PR / contributor metadata
|
||
├── README.md # contributor guide
|
||
└── <module-folder>/ # each module
|
||
```
|
||
|
||
应用会同时拉取 `registry.json` 与 `submissions.json`，仅展示两者皆存在的模块，使应用内目录与已实际合并的 PR 保持一致。提交文件还会记录每位模块贡献者，因此目录会显示堆叠头像及贡献者排行榜。目录文件与模块图标优先经全局镜像路由，`raw.githubusercontent.com` 与 jsDelivr 作为自动回退，确保商店在全球（含中国大陆）快速加载。
|
||
|
||
- 用户打开 **Extension Modules** 并点击商店图标。
|
||
- 贡献者在 `modules/` 下新增文件夹，更新 `registry.json`，并提交 PR。
|
||
- 默认客户端缓存为一小时，已合并模块无需更新应用即可生效。
|
||
|
||
高层架构见此处；规范的提交规则、字段 schema、审阅清单及 CI 校验细节见 [`modules/README.md`](modules/README.md)。
|
||
|
||
社区市场仅承载 JS/CSS 扩展模块。**浏览器扩展（MV3）** 已不再纳入社区目录 — 改为在 **Browser Extensions** 标签页实时搜索 Chrome Web Store：输入关键词、浏览结果，并通过现有 CRX 管道按需安装。实时搜索需要能够访问 Google 的网络。
|
||
|
||
## 架构
|
||
|
||
- 本仓库包含 **三个 Gradle 模块**：`app`（完整的构建器与宿主）、`shell`（嵌入到生成 APK 中的运行时宿主），以及 `clone-host`（应用克隆用的宿主代码——编译为 `classes.jar`，通过 d8 转换为 DEX，并作为资源打包进 `AppCloner`）。
|
||
- 运行时代码使用 `app` 编写，并同步到 `shell`，因此共享的 WebView/运行时行为拥有单一事实来源（single source of truth）（`core/shell`、`core/webview`、`core/engine`、`core/extension`、`ui/shell` 等）。
|
||
- APK 构建器在二进制 AXML/ARSC 层面修补模板 APK，注入配置/资源，裁剪权限，并使用 `apksig` 签名。另一条独立的加密构建路径（`EncryptedApkBuilder`）提供资源加密、加壳与完整性校验。
|
||
- 宿主刻意固定 `targetSdk = 28`——正是它让生成的应用能够从应用存储中 fork+exec 原生运行时（Node.js、PHP、Python、Go、WordPress），这是 URL 包装类工具所不具备的能力。AAB 导出器会单独重写 `targetSdk`，以适配 Play Store 分发。
|
||
- 服务端运行时与可选的 GeckoView 原生运行时均在首次使用时下载，而非内置在基础 APK 中。
|
||
- 配置中心是 `WebApp`（`data/model/WebApp.kt`）及其 `*Config` 类——所有功能设置的单一事实来源，经完整打包透传链传递到生成的 APK 中。
|
||
|
||
## 技术栈
|
||
|
||
- Kotlin、Jetpack Compose、Material 3
|
||
- Koin 用于依赖注入
|
||
- Room 2.7.2 + KSP 用于持久化
|
||
- OkHttp 4.12.0 + `okhttp-dnsoverhttps`
|
||
- `com.android.tools.build:apksig` 8.3.0 用于 APK 签名
|
||
- `protobuf-javalite` 3.25.5 用于 AAB 元数据
|
||
- GeckoView 作为可选浏览器引擎
|
||
- Coil 用于图片/视频/GIF 加载
|
||
- AndroidX Security Crypto + DataStore 用于存储密钥
|
||
- Vico Compose-M3 用于图表
|
||
- ZXing 用于二维码分享
|
||
- Apache Commons Compress + xz 用于项目导入与网站爬取
|
||
- 通过 JNI 的原生 C++ 实现 `node_launcher` 和 `go_exec_loader`
|
||
- Robolectric 用于单元测试
|
||
|
||
完整依赖列表见 [app/build.gradle.kts](app/build.gradle.kts)。
|
||
|
||
## 从源码构建
|
||
|
||
要求：Android Studio Hedgehog 或更高版本，JDK 17。Gradle wrapper 固定使用 Gradle 9.4.1。
|
||
|
||
```bash
|
||
git clone https://github.com/shiaho777/web-to-app.git
|
||
cd web-to-app
|
||
./gradlew assembleDebug
|
||
```
|
||
|
||
发布版构建请通过 `local.properties` 和 `app/build.gradle.kts` 配置签名。
|
||
|
||
## 贡献
|
||
|
||
| 通道 | 你要做的事 | 指南 |
|
||
| --- | --- | --- |
|
||
| `modules/` | 向应用内市场发布社区模块 | [modules/README.md](modules/README.md) |
|
||
| Issues | 报告 Bug 或请求功能 | [GitHub Issues](https://github.com/shiaho777/web-to-app/issues) |
|
||
| Code | 修复 Bug 或在 Android 客户端中构建功能 | [CONTRIBUTING.md](.github/CONTRIBUTING.md) |
|
||
|
||
## 联系方式
|
||
|
||
由 **shiaho** 开发。
|
||
|
||
| 平台 | 链接 |
|
||
| --- | --- |
|
||
| GitHub | [github.com/shiaho777/web-to-app](https://github.com/shiaho777/web-to-app) |
|
||
| Telegram | [t.me/webtoapp777](https://t.me/webtoapp777) |
|
||
| X (Twitter) | [@shiaho777](https://x.com/shiaho777) |
|
||
| Bilibili | [b23.tv/8mGDo2N](https://b23.tv/8mGDo2N) |
|
||
| QQ 群 | 1041130206 |
|
||
|
||
## 许可证
|
||
|
||
[The Unlicense](LICENSE)。
|
||
|
||
强制运行、BlackTech、设备伪装和 Icon Storm 等高级功能仅供技术演示，必须在用户知情同意的前提下使用。
|
||
|
||
<div align="center">
|
||
|
||
**开源 · 为 Android 高级用户打造 · Star 以支持本项目**
|
||
|
||
</div>
|