> [!NOTE]
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
> [English](./README.en.md) · [原始项目](https://github.com/shiaho777/web-to-app) · [上游 README](https://github.com/shiaho777/web-to-app/blob/HEAD/README.md)
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。
# 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)
[](#)
与众不同之处 ·
可构建内容 ·
能力概览 ·
功能地图 ·
模块市场 ·
架构 ·
构建
---
---
## What makes WebToApp different
大多数「网站转 App」工具止步于用 WebView 封装 URL。WebToApp 更接近口袋里的 APK 工坊，难点恰恰在于它与众不同之处：
- **在设备上运行真实的服务器运行时。** Node.js、PHP、Python、Go 和 WordPress 以原生二进制形式从应用存储中 fork+exec 执行——类似 Termux，但打包成可安装的 APK。URL 封装类工具完全做不到这一点。
- **内置加固的反审查网络栈。** DNS-over-HTTPS（DoH）、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 |
| --- | --- |
| **构建目标** | Web · HTML · Frontend · WordPress · Node.js · PHP · Python · Go · Image · Video · Gallery · Multi-Web |
| **浏览器引擎** | 默认系统 WebView；可选 GeckoView（Firefox）运行时以支持 ECH / SNI 加密 |
| **网络与反审查** | DoH（7 家提供商）、TLS 指纹伪装 + MITM 桥接、ECH、静态/PAC/SOCKS5 代理、CORS 绕过 |
| **隐私与加固** | 50+ 向量浏览器指纹伪装、资源加密（AES-256-GCM）、反调试、激活码门控 |
| **本地运行时** | 原生 Node.js 18.20、PHP 8.4 + Composer 2.10、Python 3.14、官方 Go 1.26、基于 SQLite 的 WordPress 7.x |
| **扩展** | 内置模块、配合 `GM_*` 的 userscript、MV3 Chrome 扩展、Chrome Web Store 实时搜索 |
| **APK/AAB 输出** | 设备端 V1/V2/V3 签名、带 targetSdk 重写的 Google Play AAB 导出、keystore 管理 |
| **AI 编码** | 提示词驱动生成 Web 应用、模块、userscript 和运行时项目；429/5xx 自动重试 |
| **宿主语言** | **10 种 UI 语言** — 中文 · English · العربية · Português · Español · Français · Deutsch · Русский · 日本語 · 한국어（阿拉伯语 RTL） |
---
## What you can build
| Input | Output | Good for |
| --- | --- | --- |
| 网站 URL | 基于 WebView 的 APK | 落地页、工具、仪表盘、文档、内部系统 |
| HTML / 静态前端 | 由 localhost 支撑的 APK | React、Vue、Vite、静态构建、离线 Web 应用 |
| Node.js / PHP / Python / Go | 内置本地服务器的 APK | 小型服务端应用、管理工具、演示、原型 |
| WordPress | 本地 PHP + SQLite 运行 WordPress 的 APK | 便携站点、主题/插件演示、内容包 |
| 图片 / 视频 / 图库 | 以媒体为主的 APK | 相册、课程资料、作品集、离线查看器 |
| 多个站点 | 标签页/卡片/信息流/抽屉式多 Web APK | 链接聚合、门户、应用合集 |
| 已安装 APK | 换标克隆或快捷方式伪装 | 图标/名称/包名实验、重打包研究 |
---
## Full feature map
WebToApp 拥有大量开关。以下按用例分组，并保持可折叠，以便页面顶部易于浏览。
🌐 浏览器引擎与网络
- **双引擎** — 默认系统 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（DoH）** — 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 文件夹，通过完整打包透传链接入。
🛡️ 隐私、指纹防御与加固
- **跨 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、字体、headers 和 IP 表面。
- **激活码门控** — 本地验证，或使用 EC P-256 签名的自有 HTTPS 端点。参见[远程激活文档](.github/docs/remote-activation.md)。
📦 本地服务端运行时（设备端 fork + exec）
- **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/打包二进制无法访问系统解析器的问题。
🧩 扩展与自动化
- **内置模块** — 视频下载（YouTube / Bilibili / Douyin / Xiaohongshu 提取器）、带 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 模式退出时会等待用户批准。
📱 应用体验
- **启动页** — 图片或视频，支持跳过行为、裁剪区间与固定方向。
- **背景音乐** — 播放列表支持同步 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 健康监控。
🔧 APK / AAB 导出与签名
- **自定义包名**、`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/.SF` / `.RSA` 自定义 V1 签名器文件名。
- **性能选项** — 图片压缩、WebP 转换、代码压缩、懒加载、DNS 预取及 preload 提示。
- **完整项目与应用数据备份/恢复。**
🗂 文件管理与项目工具
- **文件管理器** — 单屏查看、分享、安装、打开并清理构建产物（APK 构建、AAB 导出、应用克隆、构建日志）及用户文件目录，附带只读构建日志查看器。
- **网站抓取器**，用于离线包 — HTML、CSS、JS、图片、字体、`url()`、`srcset`、`@import`、路径重写、同域限制、深度限制与大小限制；并行流式 worker 池，主线程进度回调。
- **多 Web 布局** — 标签页、卡片、信息流、抽屉，各站点图标/主题色/提取选择器/刷新间隔，以及共享 JS/CSS。
- **图库应用** — 分类媒体、网格/列表/时间线视图、随机/单曲循环、排序、缩略图栏、浮层、自动下一首及播放记忆。
- **App Modifier** — 快捷方式伪装或真实二进制克隆，含 manifest/资源修补与重新签名。
🔬 专用工具与研究功能
- **Forced-run**、**BlackTech**、**device disguise** 与 **Icon Storm** 仅供技术演示，必须在用户知情同意后方可使用。
---
## 模块市场
WebToApp 拥有基于 GitHub 的模块市场，供社区贡献 JS/CSS 扩展模块。目录即本仓库中的文件，因此贡献走常规 pull-request 流程。
```
modules/
├── registry.json # app-facing catalog
├── submissions.json # CI-generated PR / contributor metadata
├── README.md # contributor guide
└── / # 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/运行时行为具有单一来源（`core/shell`、`core/webview`、`core/engine`、`core/extension`、`ui/shell` 等）。
- APK 构建器在二进制 AXML/ARSC 层级修补模板 APK，注入配置/资源，裁剪权限，并使用 `apksig` 签名。另一条加密构建路径（`EncryptedApkBuilder`）提供资源加密、加壳（shelling）和完整性校验。
- 宿主有意固定 `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 的 Native 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 等高级功能仅供技术演示，且必须在用户知情同意后方可使用。
**开源 · 为 Android 进阶用户打造 · Star 支持本项目**