企业官网建设流程全解析

1. 为什么我选择 WorkBuddy 而不是从零手搓一个 App

去年年底我接了个私活，需求很明确：做一个内部用的任务协作工具，要有移动端、要能推送、要能离线缓存，最重要的是——两周内上线。当时我第一反应是打开 Android Studio 新建项目，但冷静下来想了想，从零搭一个能上线的 App，光是账号体系、数据同步、文件存储这三块就够我喝一壶的。后来一个做独立开发的朋友甩给我一个词：WorkBuddy。

WorkBuddy 本质上是一个帮你快速搭建工作台类应用的开发框架，它把常见的后端能力（用户认证、数据库、文件存储、实时订阅）和前端壳子（WebView 容器、原生桥接、进度条管理）打包好了，你只需要关注业务逻辑本身。配合 Supabase 做后端，整个开发链路会变得非常短。我最终用六个阶段把它推上了线，中间踩了十六个坑，这篇文章就是把整个过程拆开讲清楚。

这篇文章适合谁看？如果你是有一定前端基础、想快速验证一个 App 想法的独立开发者，或者你是一个小团队的技术负责人，需要在有限时间内交付一个可用的移动端产品，那这篇内容应该能帮你省下不少试错时间。我不会只给你步骤，我会告诉你每个决策背后的原因，以及那些文档里不会写的坑。

2. 六个阶段的整体拆解与时间分配

2.1 阶段划分的逻辑：为什么是这六步

我把整个项目拆成了六个阶段：环境搭建与项目初始化、WebView 容器与原生桥接、Supabase 后端接入、核心业务功能开发、打包与签名配置、上线前的兼容性测试。这个划分不是拍脑袋来的，而是按照"依赖关系"排的——每一步的产出都是下一步的输入。

举个具体的例子，为什么 WebView 容器要放在 Supabase 接入之前？因为 WebView 的调试环境一旦跑通，你后面所有业务代码都可以在浏览器里先验证，再放进容器里跑。如果你先接后端，你会发现每次调接口都要重新打包 APK，那个循环太慢了。我实测下来，先在 Chrome 里把 Supabase 的增删改查跑通，再塞进 WebView，效率至少提升三倍。

时间分配上，我两周的实际投入大概是这样的：环境搭建半天，WebView 容器两天，Supabase 接入一天半，核心业务四天，打包签名一天，兼容性测试两天。剩下的时间全在填坑。下面这张表是我建议的时间预算，你可以根据自己的熟悉程度调整。

2.2 每个阶段的验收标准

我给自己定了一个规矩：每个阶段必须有明确的验收标准，不达标不进入下一阶段。环境搭建的验收标准是"能跑起来一个空白 Activity 并且不报错"，WebView 容器的标准是"能加载一个本地 HTML 并且 JS 能调用原生方法"，Supabase 的标准是"能从 App 里写入一条数据并在后台看到"。

这个规矩救了我好几次。有一次我在 WebView 阶段发现进度条一直卡在 80% 不动，如果当时硬着头皮往下做，后面所有页面加载都会有问题。后来排查发现是onProgressChanged回调里我漏了一个判断条件，导致进度条在某个区间反复重置。这种问题越早发现越好，因为它的影响面会随着项目推进越来越大。

3. WebView 容器搭建中最容易翻车的三个细节

3.1 进度条不是加个 ProgressBar 就完事

很多人以为 WebView 的进度条就是放一个ProgressBar，然后在onProgressChanged里更新进度就完了。我一开始也是这么想的，结果实测发现两个问题：第一，进度条在页面加载完成后不会自动消失，因为newProgress到 100 之后还会回调几次；第二，快速切换页面时进度条会闪烁，因为旧的加载还没结束新的就开始了。

正确的做法是在onProgressChanged里加一个判断：只有当newProgress大于等于 100 时才隐藏进度条，并且用一个标志位记录当前是否正在加载。另外，进度条的样式建议用横向的HorizontalProgressBar，不要用圆形的，因为横向的视觉反馈更符合"页面加载"这个语义。

webView.setWebChromeClient(new WebChromeClient() { @Override public void onProgressChanged(WebView view, int newProgress) { if (newProgress >= 100) { progressBar.setVisibility(View.GONE); isLoading = false; } else { if (!isLoading) { progressBar.setVisibility(View.VISIBLE); isLoading = true; } progressBar.setProgress(newProgress); } } });

这段代码看起来简单，但isLoading这个标志位是关键。没有它，进度条会在每次回调时重新显示，造成闪烁。我踩这个坑的时候排查了快一个小时，最后用日志打印每次回调的值才定位到。

3.2 文件访问权限：content:// 协议的那些事

WebView 加载本地文件时，你会遇到content://开头的 URI。这个协议是 Android 的文件提供者机制，目的是让应用之间安全地共享文件。但 WebView 默认是不允许访问content://的，你需要手动开启setAllowContentAccess(true)和setAllowFileAccess(true)。

这里有个坑：从 Android 10 开始，setAllowFileAccess对file://协议的访问被限制了，你必须用content://或者WebViewAssetLoader。我当时的做法是用WebViewAssetLoader把本地资源映射到一个虚拟的 HTTPS 域名下，这样既安全又不会触发权限问题。

WebViewAssetLoader assetLoader = new WebViewAssetLoader.Builder() .addPathHandler("/assets/", new WebViewAssetLoader.AssetsPathHandler(this)) .build(); webView.setWebViewClient(new WebViewClientCompat() { @Override public WebResourceResponse shouldInterceptRequest(WebView view, WebResourceRequest request) { return assetLoader.shouldInterceptRequest(request.getUrl()); } });

用WebViewAssetLoader之后，你的本地页面地址会变成https://appassets.androidplatform.net/assets/index.html这种形式，WebView 会把它当成正常的 HTTPS 请求处理，省掉很多权限麻烦。

3.3 原生桥接：JS 调用 Android 方法的安全边界

WebView 和原生代码的通信靠addJavascriptInterface。这个方法的坑在于：如果你在 Android 4.2 以下使用，会有安全漏洞，因为反射机制可以被恶意 JS 利用。虽然现在最低版本基本都是 5.0 以上了，但你还是应该加一个@JavascriptInterface注解，并且只暴露必要的方法。

我当时的做法是定义一个Bridge类，里面只放三个方法：getToken()、saveData()、showToast()。其他所有业务逻辑都走 Supabase 的 HTTP 接口，不通过桥接。这样即使 WebView 被注入，攻击面也很小。

注意：addJavascriptInterface注入的对象方法必须在主线程执行，如果你在方法里做耗时操作，一定要开子线程，否则会阻塞 WebView 的渲染。

4. Supabase 接入：从建表到行级安全策略

4.1 为什么选 Supabase 而不是自己搭后端

Supabase 本质上是一个开源的 Firebase 替代品，它基于 PostgreSQL，提供了自动生成的 REST API、实时订阅、用户认证和文件存储。我选它的原因很简单：我不需要写一行后端代码，就能让 App 读写云端数据。

但这里有个前提：你的数据结构不能太复杂。Supabase 的行级安全策略（RLS）是基于 SQL 的，如果你需要复杂的权限逻辑，比如"只有任务创建者才能删除任务，但协作者可以修改状态"，那你就得写比较复杂的策略。我当时的做法是把权限逻辑简化成"创建者全权，协作者只读"，这样策略就很好写。

4.2 建表与 RLS 策略的实操步骤

首先在 Supabase 控制台建一张tasks表，字段包括id、title、status、owner_id、created_at。然后开启 RLS，添加两条策略：一条是SELECT策略，允许所有登录用户读取；一条是ALL策略，只允许owner_id等于当前用户 ID 的用户进行增删改。

-- 开启行级安全 ALTER TABLE tasks ENABLE ROW LEVEL SECURITY; -- 读取策略：所有登录用户可读 CREATE POLICY "tasks_select" ON tasks FOR SELECT USING (auth.role() = 'authenticated'); -- 写入策略：只有创建者可操作 CREATE POLICY "tasks_modify" ON tasks FOR ALL USING (auth.uid() = owner_id);

这两条策略看起来简单，但auth.uid()这个函数只有在请求携带了有效的 JWT 时才会返回用户 ID。如果你在 App 里没有正确设置Authorization头，策略会直接拒绝所有请求，而且错误信息很模糊，只会告诉你"权限不足"。

4.3 实时订阅的坑：连接断开与重连

Supabase 的实时订阅基于 WebSocket。在移动端，WebSocket 会因为网络切换、后台切换而断开。我一开始没处理重连，结果用户切到后台再回来，数据就不更新了。后来加了一个重连逻辑：监听onError和onClose事件，在断开后延迟 3 秒重新订阅。

let subscription = supabase .from('tasks') .on('*', payload => { console.log('数据变化:', payload); }) .subscribe((status) => { if (status === 'CLOSED' || status === 'CHANNEL_ERROR') { setTimeout(() => { subscription.unsubscribe(); subscribeToTasks(); }, 3000); } });

这个重连逻辑我建议你直接抄，因为移动端的网络环境太复杂了，没有重连的实时订阅基本不可用。

5. 打包签名与兼容性测试：上线前的最后两道关

5.1 签名配置：为什么你的 release 包装不上

Android 的 release 包必须签名才能安装。我一开始用 Android Studio 自动生成的签名，结果发现每次构建都会生成新的签名文件，导致覆盖安装失败。正确的做法是手动生成一个 keystore 文件，然后在build.gradle里固定引用它。

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

这里有个细节：minifyEnabled true会开启代码混淆，但 WebView 的桥接类不能被混淆，否则 JS 调用会失败。你需要在proguard-rules.pro里加上-keepclassmembers class com.yourpackage.Bridge { public *; }。

5.2 低版本 WebView 内核的兼容性处理

Android 的 WebView 内核版本是跟着系统走的，低版本系统的 WebView 内核可能不支持某些 ES6 语法。我实测发现，Android 8.1 的 WebView 内核大概相当于 Chrome 60 左右，不支持可选链操作符（?.）和空值合并运算符（??）。

解决办法有两个：一是用 Babel 把代码转成 ES5，二是在 WebView 初始化时检测内核版本，如果太低就提示用户升级。我选的是第一种，因为转译的成本更低，而且不影响用户体验。

// 在 WebView 里检测内核版本 const ua = navigator.userAgent; const match = ua.match(/Chrome\/(\d+)/); if (match && parseInt(match[1]) < 60) { alert('您的浏览器内核版本过低，请升级系统或使用最新版浏览器'); }

5.3 多机型测试的优先级排序

兼容性测试不可能覆盖所有机型，我的做法是按优先级排序：先测主流品牌的中低端机（因为性能瓶颈最容易暴露），再测高端机（验证功能完整性），最后测平板和折叠屏（验证布局适配）。我当时的测试清单是这样的：

这个排序的逻辑是：中低端机的性能问题会直接影响可用性，必须优先解决；高端机的功能问题通常是个例，可以后续修复；平板和折叠屏的用户占比低，可以放到最后。

6. 十六个坑里最值得说的五个

6.1 坑一：Android Studio 依赖解析失败

这个坑我放在第一个，因为它太常见了。报错信息通常是Could not resolve all task dependencies for configuration ':app:debugCompileClasspath'。原因一般是网络问题或者仓库配置不对。我的解决办法是在settings.gradle里加上阿里云的镜像仓库，并且把google()和mavenCentral()的顺序调整一下。

dependencyResolutionManagement { repositories { maven { url 'https://maven.aliyun.com/repository/google' } maven { url 'https://maven.aliyun.com/repository/central' } google() mavenCentral() } }

提示：如果你用的是公司网络，可能需要配置代理才能访问外部仓库。但代理配置这块我不展开讲，你懂的。

6.2 坑二：WebView 白屏但控制台无报错

白屏是最让人头疼的问题，因为没有任何错误信息。我排查了三个小时，最后发现是WebViewClient的shouldOverrideUrlLoading返回了true，导致所有 URL 都被拦截了。正确的做法是：对于内部页面返回false，让 WebView 自己处理；对于外部链接返回true，用系统浏览器打开。

@Override public boolean shouldOverrideUrlLoading(WebView view, WebResourceRequest request) { String url = request.getUrl().toString(); if (url.startsWith("https://appassets.androidplatform.net")) { return false; // 内部页面，WebView 自己处理 } // 外部链接，用系统浏览器打开 Intent intent = new Intent(Intent.ACTION_VIEW, Uri.parse(url)); startActivity(intent); return true; }

6.3 坑三：Supabase 的 JWT 过期导致请求失败

Supabase 的 JWT 默认有效期是一小时。如果你的 App 长时间在前台运行，JWT 过期后所有请求都会返回 401。我一开始没处理这个，结果用户用了一个小时后突然所有操作都失败。后来加了一个拦截器，在请求返回 401 时自动刷新 token。

async function fetchWithAuth(url, options = {}) { const { data: { session } } = await supabase.auth.getSession(); if (!session) { await supabase.auth.refreshSession(); } return fetch(url, { ...options, headers: { ...options.headers, 'Authorization': `Bearer ${session.access_token}` } }); }

6.4 坑四：进度条与页面加载不同步

这个坑我在 3.1 里提过，但这里再补充一个细节：如果你的页面里有大量图片，onProgressChanged的进度值会在 90% 左右停留很久，因为图片加载不计入进度。解决办法是用onPageFinished回调来隐藏进度条，而不是依赖进度值到 100。

6.5 坑五：release 包安装后闪退

release 包闪退的原因通常是混淆导致的。我遇到过一次，是因为 Supabase 的 SDK 里用了反射，被 ProGuard 混淆后找不到类。解决办法是在proguard-rules.pro里加上-keep class com.supabase.** { *; }。这个规则会保留 Supabase 相关的所有类，避免混淆问题。

7. 可复用的经验清单与后续扩展方向

7.1 我总结的十条经验

第一，环境搭建阶段一定要用镜像仓库，否则依赖解析能卡你半天。第二，WebView 容器先用浏览器调通再塞进去，效率翻倍。第三，Supabase 的 RLS 策略一定要在控制台先测试，不要直接在 App 里试。第四，进度条的逻辑要加标志位，否则会闪烁。第五，文件访问用WebViewAssetLoader，不要用file://。第六，桥接类只暴露必要方法，减少攻击面。第七，实时订阅必须加重连逻辑。第八，签名文件要固定，不要每次重新生成。第九，混淆规则要保留 WebView 桥接类和第三方 SDK。第十，兼容性测试按优先级排序，先测中低端机。

7.2 后续可以扩展的方向

这个 App 上线后，我陆续加了一些功能：离线缓存（用 IndexedDB 存任务列表）、推送通知（用 Supabase 的 Edge Function 触发）、深色模式（用 CSS 变量切换）。如果你也想扩展，我建议先从离线缓存开始，因为它的实现成本最低，但用户体验提升最明显。

另外，WorkBuddy 本身也在迭代，我最近看到它支持了自定义技能（Skill）的机制，你可以把常用的操作封装成 Skill，然后在工作台里直接调用。这个机制我还没深入用，但看起来很适合做自动化流程。如果你对这个方向感兴趣，可以先去研究一下它的 Skill 文档，我后续也会写一篇关于 Skill 开发的实操记录。

最后说一个我个人的体会：用 WorkBuddy 搭 App 最大的价值不是省了多少代码，而是它帮你把那些"必须做但没技术含量"的事情标准化了。你不需要再纠结用哪个库做认证、用哪个方案做存储，直接用它给的方案就行。省下来的时间，你可以花在真正影响用户体验的细节上，比如进度条的动画、错误提示的文案、加载失败的兜底页面。这些细节才是用户能感知到的。