shiahonb777--web-to-app/README.md

Note

本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
English · 原始项目 · 上游 README
原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

WebToApp

在手机上直接从 Web 项目构建 Android APK。

一款设备端 APK 工坊，远不止 URL 封装——它能 fork 并执行完整的服务器运行时、内置加固的反审查网络栈、为 Google Play 签名打包，并运行 MV3 浏览器扩展，全程无需 PC 或远程构建服务器。

English · 简体中文

与众不同之处 · 可构建内容 · 能力概览 · 功能地图 · 模块市场 · 架构 · 构建

---

---

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 拥有大量开关。以下按用例分组，并保持可折叠，以便页面顶部易于浏览。

🌐 Browser engine & networking

• 双引擎 — 默认系统 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 文件夹，经完整打包透传链接入。

🛡️ Privacy, fingerprint defense & hardening

• 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 端点。详见远程激活文档。

📦 本地服务端运行时（设备上 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 / 抖音 / 小红书提取器）、带 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/<name>.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
└── <module-folder>/     # each module

应用会同时拉取 registry.json 与 submissions.json，仅展示两者皆存在的模块，使应用内目录与已实际合并的 PR 保持一致。提交文件还会记录每位模块贡献者，因此目录会显示堆叠头像及贡献者排行榜。目录文件与模块图标优先经全局镜像路由，raw.githubusercontent.com 与 jsDelivr 作为自动回退，确保商店在全球（含中国大陆）快速加载。

• 用户打开 Extension Modules 并点击商店图标。
• 贡献者在 modules/ 下新增文件夹，更新 registry.json，并提交 PR。
• 默认客户端缓存为一小时，已合并模块无需更新应用即可生效。

高层架构见此处；规范的提交规则、字段 schema、审阅清单及 CI 校验细节见 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。

从源码构建

要求：Android Studio Hedgehog 或更高版本，JDK 17。Gradle wrapper 固定使用 Gradle 9.4.1。

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
Issues	报告 Bug 或请求功能	GitHub Issues
Code	修复 Bug 或在 Android 客户端中构建功能	CONTRIBUTING.md

联系方式

由 shiaho 开发。

平台	链接
GitHub	github.com/shiaho777/web-to-app
Telegram	t.me/webtoapp777
X (Twitter)	@shiaho777
Bilibili	b23.tv/8mGDo2N
QQ 群	1041130206

许可证

The Unlicense。

强制运行、BlackTech、设备伪装和 Icon Storm 等高级功能仅供技术演示，必须在用户知情同意的前提下使用。

开源 · 为 Android 高级用户打造 · Star 以支持本项目