企业官网建设流程全解析

1. 从零到上线：为什么我选择 WorkBuddy 而不是纯手写

去年年底我接了一个内部工具类 App 的活儿，需求很明确：一个轻量的移动端应用，能跑在 Android 上，核心页面用 WebView 承载已有的 H5 内容，同时要能调用几个原生能力（文件选择、进度提示、外部唤起）。预算不多，时间更紧，团队里能写原生 Android 的人只有一个，还同时压着别的项目。

摆在面前的路其实就三条：纯原生写、跨端框架、或者用 AI 辅助工具把骨架搭出来再补细节。纯原生最稳但最慢，跨端框架学习成本和打包链路又是一堆坑。最后我选了第三条路——用 WorkBuddy 这类 AI 辅助开发工具来生成项目骨架和大部分样板代码，然后自己接管关键环节。

这个选择背后的逻辑很简单：App 上线真正难的不是写代码，而是把一堆琐碎的配置、权限、兼容性、打包签名、WebView 交互这些"脏活"串起来。这些活儿有大量重复模式，正好是 AI 辅助工具擅长的。而真正需要人判断的——比如 WebView 的安全策略、文件路径的适配、进度条的状态机——AI 给的是起点，不是终点。

所以这篇东西不是 WorkBuddy 的软文，也不是什么"三分钟上线一个 App"的爽文。我想把整个流程拆成六个阶段，把我在每个阶段踩过的坑（一共十六个，都是真金白银换来的）摊开讲清楚。适合谁看？适合那些手上有 H5 资产、想快速包一个能上架的 App、又不想被原生开发拖死的开发者；也适合已经在用 AI 辅助工具、但发现"生成完就跑不起来"的人。

WorkBuddy 在这里的角色，说白了就是一个"懂 Android 项目结构的结对伙伴"。它能帮你把 Android Studio 工程、Gradle 配置、Manifest 权限、WebView 容器 Activity 这些一次性生成出来，省掉大量查文档的时间。但生成之后能不能跑、跑起来会不会崩、上架会不会被拒，还是得靠你自己一个个环节去验证。下面这六个阶段，就是我实际走下来的完整路径。

2. 阶段一：需求拆解与项目骨架搭建

2.1 先想清楚"哪些用 WebView，哪些必须原生"

很多人一上来就让 AI 生成整个项目，结果生成出来的东西结构混乱，改都不知道从哪改。我的做法是先做一次需求分层，把功能拆成三类：

• 纯展示类：文章列表、详情页、设置页——这些全部交给 WebView，H5 里已经有的直接复用。
• 需要原生能力类：文件选择、图片保存、进度条、外部 App 唤起——这些必须走原生桥接。
• 系统级交互类：权限申请、通知、后台任务——这些只能原生做。

拆完你会发现，真正需要写原生代码的部分其实很少，大部分是 WebView 容器加几个 JSBridge 方法。这个判断很关键，因为它决定了你后面让 WorkBuddy 生成什么、自己补什么。

2.2 用 WorkBuddy 生成骨架的正确姿势

我试过两种方式。第一种是直接说"帮我做一个 Android App"，生成出来的东西大而全，但很多用不上，反而干扰。第二种是按模块分次生成，效果好得多。

具体做法是：先让它生成一个最小的可运行工程（一个 Activity + 一个 WebView），确认能编译能跑；然后再逐个模块加功能。每次生成后立刻在 Android Studio 里同步、编译、跑一遍。这样出问题能马上定位到是哪次生成引入的。

生成骨架时我给的描述大概是这样："生成一个 Android 项目，minSdk 24，targetSdk 34，主 Activity 里放一个全屏 WebView，加载本地 assets 下的 index.html，开启 JavaScript 和 DOM Storage，处理返回键回退网页。"这种颗粒度的描述，AI 给的代码基本能直接用。

注意：WorkBuddy 生成的 Gradle 版本和 Android Gradle Plugin 版本经常和你本地 Android Studio 不匹配。第一次同步大概率报错，别慌，看报错信息把版本号对齐就行。我一般会先确认本地 Android Studio 自带的 AGP 版本，再反过来改 build.gradle。

2.3 骨架阶段的三个坑

坑一：包名和 applicationId 不一致。AI 生成时经常把 namespace 和 applicationId 写成两个不同的值，编译能过，但打包签名时会出问题。一定要在 build.gradle 里确认这两个一致。

坑二：assets 目录位置放错。WebView 加载本地文件，assets 必须放在src/main/assets，不是src/main/res/assets。放错了就是白屏，而且不报错，特别难查。

坑三：忘记加 INTERNET 权限。如果你的 H5 里有任何网络请求，Manifest 里必须声明android.permission.INTERNET。这个坑低级但高频，我见过不止一个人卡在这。

3. 阶段二：WebView 容器的核心配置与安全策略

3.1 WebView 初始化：每一项设置都有理由

WebView 是这类 App 的心脏，配置错了要么功能缺失，要么安全出问题。我把关键设置和理由列一下：

WebView webView = findViewById(R.id.webview); WebSettings settings = webView.getSettings(); settings.setJavaScriptEnabled(true); // H5 交互必需 settings.setDomStorageEnabled(true); // localStorage/sessionStorage 必需 settings.setDatabaseEnabled(true); // 部分老 H5 依赖 settings.setAllowFileAccess(true); // 加载本地资源 settings.setAllowContentAccess(true); // 处理 content:// URI settings.setMixedContentMode(WebSettings.MIXED_CONTENT_COMPATIBILITY_MODE); settings.setCacheMode(WebSettings.LOAD_DEFAULT);

这里每一项都不是随便加的。setDomStorageEnabled不加，很多现代前端框架直接白屏；setAllowContentAccess不加，文件选择回调拿到的content://URI 读不了。setMixedContentMode要谨慎，如果你的 H5 全是 HTTPS，建议用MIXED_CONTENT_NEVER_ALLOW，更安全。

3.2 处理返回键：别让用户一按就退出

WebView 的返回键处理是新手最容易忽略的。默认行为是按返回键直接退出 Activity，但用户期望的是"网页能回退就回退，回退不了才退出"。标准写法：

@Override public void onBackPressed() { if (webView.canGoBack()) { webView.goBack(); } else { super.onBackPressed(); } }

看起来简单，但有个细节：如果网页里有弹窗或者单页应用的路由，canGoBack()可能不准。我遇到过一个 SPA 项目，路由切换不产生历史记录，导致返回键直接退出。解决办法是让前端在路由变化时通过 JSBridge 通知原生，原生维护一个自己的栈。

3.3 WebViewClient 与 WebChromeClient 的分工

这两个类经常被搞混。简单说：WebViewClient 管页面加载和跳转，WebChromeClient 管 JS 交互和 UI 相关（进度、标题、弹窗、文件选择）。

webView.setWebViewClient(new WebViewClient() { @Override public boolean shouldOverrideUrlLoading(WebView view, WebResourceRequest request) { String url = request.getUrl().toString(); if (url.startsWith("http")) { view.loadUrl(url); return true; } // 处理自定义 scheme，比如唤起外部 App return handleCustomScheme(url); } });

shouldOverrideUrlLoading是拦截跳转的关键。所有非 HTTP 的 scheme（比如某些 App 的唤起链接）都要在这里拦下来，否则 WebView 会报错或者无响应。

3.4 安全策略：这几个开关千万别乱开

• setAllowUniversalAccessFromFileURLs：默认 false，开了会让本地文件能访问任意网络资源，有安全风险，除非你明确知道在干什么，否则别开。
• setAllowFileAccessFromFileURLs：同理，谨慎。
• setJavaScriptCanOpenWindowsAutomatically：一般不需要开。

实操心得：如果你的 App 要上架应用市场，审核时可能会检查 WebView 的安全配置。把setAllowUniversalAccessFromFileURLs保持默认 false，能省掉不少解释的麻烦。

4. 阶段三：JSBridge 双向通信与原生能力桥接

4.1 为什么需要 JSBridge，而不是直接 evaluateJavascript

H5 调原生，最原始的方式是addJavascriptInterface，但它在 Android 4.2 以下有安全漏洞，而且只能同步调用。现代做法是用@JavascriptInterface注解（4.2+ 安全），配合evaluateJavascript做原生调 H5 的回调。

我的方案是封装一个统一的 Bridge：

public class JsBridge { private WebView webView; @JavascriptInterface public void callNative(String action, String params, String callbackId) { // 根据 action 分发到不同处理逻辑 // 处理完通过 evaluateJavascript 回调 String js = "javascript:window.bridgeCallback('" + callbackId + "', " + result + ")"; webView.post(() -> webView.evaluateJavascript(js, null)); } }

H5 侧调用就是window.AndroidBridge.callNative('pickFile', '{}', 'cb_1')。这种设计的好处是所有原生能力走同一个入口，加新功能不用改 H5 的调用方式，只加 action 分支。

4.2 文件选择：content:// URI 的坑

文件选择是这类 App 的高频需求，也是最容易出问题的地方。Android 从 7.0 开始，file://URI 不能直接暴露给外部，必须用FileProvider生成content://URI。

<provider android:name="androidx.core.content.FileProvider" android:authorities="${applicationId}.fileprovider" android:exported="false" android:grantUriPermissions="true"> <meta-data android:name="android.support.FILE_PROVIDER_PATHS" android:resource="@xml/file_paths" /> </provider>

file_paths.xml里要声明哪些目录可以共享。这里有个大坑：不同厂商的 App 返回的 content URI 路径格式不一样，比如某些搜索类 App 返回的路径里带external_path，某些带external_root。你的file_paths.xml要尽量覆盖这些情况，否则读取时会抛IllegalArgumentException。

我踩过的具体坑：某个 App 分享文件过来，URI 是content://com.xxx.fileprovider/external_path/android/data/...，而我的 file_paths 只声明了external-path，结果直接崩。后来把external-path、external-files-path、external-cache-path都加上才解决。

4.3 进度条：状态机比进度值更重要

WebView 的进度条看起来简单，其实状态管理很容易乱。onProgressChanged会回调很多次，如果每次都更新 UI，会出现进度条闪烁或者卡在 90% 不动的情况。

我的做法是维护一个简单状态机：

• 进度 < 100 且页面未加载完：显示进度条，更新进度。
• 进度 = 100：延迟 200ms 再隐藏，避免闪一下。
• 页面加载出错：隐藏进度条，显示错误页。

@Override public void onProgressChanged(WebView view, int newProgress) { if (newProgress < 100) { progressBar.setVisibility(View.VISIBLE); progressBar.setProgress(newProgress); } else { progressBar.postDelayed(() -> progressBar.setVisibility(View.GONE), 200); } }

注意：onProgressChanged在页面内跳转（比如 SPA 路由）时可能不触发，别指望它做所有加载状态的判断。重要状态还是靠前端主动通知。

4.4 唤起外部 App：scheme 拦截的边界

"iOS 浏览器唤起安装 App"这类需求，在 Android 上对应的是拦截自定义 scheme。但这里有个边界：不是所有 scheme 都能唤起成功，用户没装对应 App 时，shouldOverrideUrlLoading返回 true 后如果不做处理，页面会卡住。

正确做法是尝试唤起，同时设置一个超时，超时后跳转到下载页或提示页。这个逻辑 AI 一般不会主动帮你写，得自己补。

5. 阶段四：打包、签名与上架前的自检

5.1 签名配置：别把 keystore 弄丢

打包签名是上线前的最后一道坎。我的建议是在项目一开始就把签名配置好，别等到要发版了才弄。

android { signingConfigs { release { storeFile file("../keystore/release.jks") storePassword "xxx" keyAlias "xxx" keyPassword "xxx" } } buildTypes { release { signingConfig signingConfigs.release minifyEnabled true proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro' } } }

keystore 文件一定要备份，丢了就再也无法更新同一个 App 了。密码也别硬编码在 build.gradle 里，用local.properties或者环境变量。

5.2 混淆规则：WebView 和 JSBridge 必须保留

开了minifyEnabled之后，JSBridge 的@JavascriptInterface方法如果被混淆，H5 就调不到了。proguard 规则里必须加：

-keepclassmembers class * { @android.webkit.JavascriptInterface <methods>; } -keep class com.yourpackage.JsBridge { *; }

这个坑我踩过，debug 包一切正常，release 包 H5 调原生全部失效，查了半天才发现是混淆。

5.3 上架自检清单

上架前我会过一遍这个清单：

实操心得：release 包一定要在真机上完整跑一遍，尤其是 WebView 相关的功能。模拟器和 debug 包经常掩盖问题，比如混淆导致的 JSBridge 失效、签名导致的 FileProvider 权限问题。

6. 阶段五：常见问题排查与十六个坑速查

6.1 白屏问题排查路径

白屏是最高频的问题，排查顺序我总结成一条链：

1. 检查 assets 目录位置对不对。
2. 检查setJavaScriptEnabled和setDomStorageEnabled是否开启。
3. 用 Chrome 的chrome://inspect远程调试，看 Console 有没有报错。
4. 检查 H5 的资源路径是不是绝对路径（/js/app.js在 WebView 里会找不到）。
5. 检查有没有error loading webview: could not register service worker这类报错，通常是 Service Worker 在 WebView 里不支持导致的，前端要做降级。

6.2 十六个坑速查表

6.3 WebView 内存泄漏的处理

WebView 是出了名的内存泄漏大户。如果 Activity 销毁时 WebView 没正确释放，会一直持有 Context。标准做法是在onDestroy里：

@Override protected void onDestroy() { if (webView != null) { webView.loadDataWithBaseURL(null, "", "text/html", "utf-8", null); webView.clearHistory(); ((ViewGroup) webView.getParent()).removeView(webView); webView.destroy(); webView = null; } super.onDestroy(); }

这段代码看着啰嗦，但每一步都有用。loadDataWithBaseURL清空内容，clearHistory清历史，removeView从父容器移除，最后destroy。少一步都可能泄漏。

7. 阶段六：可复用经验与后续扩展方向

7.1 把配置抽成模板

走完一遍之后，我把所有配置抽成了一个模板工程：WebView 容器、JSBridge、FileProvider、进度条、返回键处理全部封装好。下次再有类似需求，直接改包名和 H5 入口就能用。这个模板的价值在于把踩过的坑固化成了默认配置，新项目不用重新踩一遍。

7.2 AI 辅助工具的边界在哪里

用 WorkBuddy 这类工具，我的体会是：它擅长生成"标准结构"，不擅长处理"边界情况"。项目骨架、Gradle 配置、基础 WebView 设置，它给得又快又准；但 FileProvider 路径适配、混淆规则、SPA 返回键这些需要结合具体场景判断的地方，它给的东西往往不够，得自己补。

所以正确的用法是：让 AI 做 70% 的样板，自己做 30% 的关键判断。指望它一键生成能上线的 App，不现实；但用它把开发时间从两周压到三天，完全可行。

7.3 后续可以扩展的方向

这个 App 上线后，我又陆续加了几个东西，都是基于同一套骨架：

• 离线缓存：用 Service Worker 加原生缓存配合，弱网下也能看内容。
• 推送：接入推送 SDK，原生侧处理通知点击跳转到对应 WebView 页面。
• 深链接：外部链接直接打开 App 内对应页面，靠 scheme 拦截加路由映射。

每加一个功能，我都会回到那个模板工程里更新，让它越来越完整。这套东西现在对我来说已经是一个"移动端 WebView 容器"的标准答案了，遇到新需求直接套，省下来的时间才是真正值钱的部分。

最后分享一个小技巧：调试 WebView 时，chrome://inspect是神器，但前提是 WebView 要开启调试。在 Application 或 Activity 里加一句WebView.setWebContentsDebuggingEnabled(true)（仅 debug 包），就能在 Chrome 里像调网页一样调 App 内的页面，Console、Network、Elements 全都有。这个开关帮我省了无数次的"盲猜"时间。