企业官网建设流程全解析

如何给WebToApp贡献代码：从Fork、本地构建到PR/CI的全流程指南

【免费下载链接】web-to-appThe most full featured web-to-app toolkit on Android, a complete APK workshop that runs entirely on your phone项目地址: https://gitcode.com/GitHub_Trending/web/web-to-app

WebToApp 是功能最全的 Web-to-App 工具箱，能完全在手机上把网页、Node.js、PHP、Python 等项目打包成 APK。本文为新手整理的WebToApp 贡献代码指南，覆盖 Fork、本地构建、提交 PR 与 CI 校验的完整流程，帮你把第一个 PR 顺利合入主线。

1️⃣ 项目结构速览：三个 Gradle 模块

WebToApp 仓库由 3 个 Gradle 模块和若干资源目录组成，动手前先认清"哪块代码在哪里"：

共享运行时代码只以app/为唯一事实来源，构建时经syncShellRuntimeSources同步进shell/。永远不要手改shell/src下的文件——它是再生成的产物。

2️⃣ 选对贡献通道：代码、模块还是文档？

官方贡献指南 .github/CONTRIBUTING.md 把贡献分为三条车道，选一条即可：

• 模块市场：几小时投入，提交一个 JS/CSS 模块，详见 modules/README.md
• 代码贡献：几天投入，修复 Bug 或开发 Android 客户端新功能
• 文档改进：编辑docs/下的页面并提交 PR，适合新手熟悉项目

💡 不确定走哪条车道？先在 Issue 区找类似讨论——动手前对齐方向，比写完再返工便宜得多。

3️⃣ 环境准备与本地构建

环境要求很轻：

• Android Studio Hedgehog 或更新版本
• JDK 17
• 无需安装系统 Gradle——wrapper 已锁定 Gradle 9.4.1
• 涉及原生代码（node_launcher、go_exec_loader、APK 优化器）时，需经 SDK Manager 安装 Android NDK + CMake（CI 使用cmake;3.22.1与ndk;28.2.13676358）

最快构建方法：Fork 后克隆

在仓库页面点击 Fork 到你名下，然后克隆本地副本：

git clone https://gitcode.com/GitHub_Trending/web/web-to-app cd web-to-app ./gradlew assembleDebug

首次构建成功后，你就有了可运行、可调试的完整构建器。

4️⃣ 提交前的本地校验：三道门禁

提交 PR 前，先跑通本地检查（完整命令清单见 docs/developer/recipes.md）：

./gradlew :app:compileStandardDebugKotlin -x syncCloneHostDex --no-configuration-cache ./gradlew :app:testStandardDebugUnitTest --no-configuration-cache -PskipShellTemplateSync=true ./gradlew :app:checkConfigFieldDrift --no-configuration-cache

动到 shell 同步的运行时代码或导出打包时，还要重建你碰过的模板：

./gradlew :shell:assembleRelease :app:syncShellTemplateApk --no-configuration-cache

预览 ≠ 导出：大多数 PR 被拒的原因

宿主应用（预览）和生成的 APK（导出）跑的是两套代码。一个编辑器开关要影响生成的 APK，必须走完整条链：模型 → ApkConfig JSON → shell 配置 → shell 同步的运行时代码。三道门禁替你把关：

• checkConfigFieldDrift——模型 / JSON / shell 字段名必须一致（Gson 会静默丢弃对不上的字段）
• WebViewConfigBooleanCoverageTest——WebViewConfig每新增一个 Boolean 都要登记并走完导出往返
• ShellUiParityTest——宿主播放器读的每个模型字段，壳播放器也必须读

更深入的改动配方见 docs/developer/recipes.md，配置字段漂移原理见 docs/developer/config-drift.md，而面向深度贡献者的架构全景指南是 AGENTS.md。

5️⃣ 标准交付流程：Issue → 分支 → PR → CI 变绿

1. 从main分出分支，一个 PR 只解决一件事
2. Issue 与 PR 请用英文写——标题、正文、评审讨论
3. PR 描述写"用户看得到的效果"，而不只是代码 diff
4. 用Fixes #N关联 Issue；Issue 只在合并时关闭，开 PR 时不关、CI 红时不关
5. 改动涉及构建系统、原生代码或 APK 打包时，附上模板重建命令的输出
6. CI 必须绿色才合并；main受分支保护，不接受直推
7. 永远不要提交密钥、keystore、local.properties或 IDE / 缓存垃圾

CI 会检查什么？

PR 触发的check任务（45 分钟超时，定义在 .github/workflows/android-ci.yml）会：

• 准备 JDK 17、Android SDK 36、NDK / CMake 环境
• 编译:app:compileStandardDebugKotlin与:shell:compileDebugKotlin（debug 变体，跳过模板同步）
• 运行单元测试:app:testStandardDebugUnitTest
• 执行:app:checkConfigFieldDrift拦截配置字段漂移

另外还有两条按路径触发的流水线：

• 改动modules/目录 → modules-check.yml 自动运行模块目录校验器
• 改动docs/目录 → docs-deploy.yml 在 PR 阶段只构建文档站以提前发现破损，合并到main后才部署上线

6️⃣ 维护者 Review 的 5 个关注点

• 正确性——经过执行验证（测试、构建产物），而不只是"读起来对"
• 安全性——动到 WebView、文件 IO、APK 签名或原生桥的改动会接受额外审查
• 聚焦——顺手做的重构请单独发 PR
• 风格——新 UI 构建在 Wta 设计系统上；用户可见文案必须覆盖全部 10 种语言，禁止用R.string加载文案
• 两条路径——"只在预览生效的功能"与"只在导出接线的配置"是两类经典翻车点

7️⃣ 新手最容易的第一步 🚀

如果对客户端代码还没信心，推荐两个低门槛入口：

1. 给市场提交模块：新建modules/<你的模块>/module.json与main.js（需要 CSS 时再加style.css），在modules/registry.json加一行索引，提 PR 即可。市场没有后端，已合并的模块会直接出现在应用内目录里。
2. 改进文档：编辑 docs/ 下的中英文页面，PR 会自动触发文档站构建校验。

相关文档索引

• 官方贡献指南：.github/CONTRIBUTING.md
• 开发者文档入口：docs/developer/index.md
• 常见改动配方：docs/developer/recipes.md
• 模块市场说明：modules/README.md
• 深度架构与约束：AGENTS.md

总结一条主线：选车道 → Fork 并本地构建 → 跑通本地三道门禁 → PR 描述用户可见效果 → CI 变绿合并。祝你的第一个 PR 顺利合入 🎉

【免费下载链接】web-to-appThe most full featured web-to-app toolkit on Android, a complete APK workshop that runs entirely on your phone项目地址: https://gitcode.com/GitHub_Trending/web/web-to-app