WorkBuddy+WebView+Supabase：三周上线跨平台App实战与16个坑

1. 为什么我选择用 WorkBuddy 从零搭一个能上线的 App去年年底我接了个私活帮一个做线下活动的小团队搭一套内部用的报名和签到工具。预算不高工期只有三周对方的要求却很实在安卓和 iOS 都要能用数据要能实时同步最好还能直接分享链接让用户点开就用。我一开始想的是原生开发Android 一套 KotliniOS 一套 Swift光环境配置和双端联调就得吃掉大半时间更别说后面还要处理推送、登录、数据库这些琐事。后来我换了个思路用 WorkBuddy 作为主力开发环境配合 WebView 容器和 Supabase 做后端硬是在两周半的时间里把东西交付出去了而且上线之后跑了三个月没出大问题。这篇文章就是把这整个过程拆开来讲。我会把从需求梳理到最终上线的六个阶段完整走一遍再把我在这个过程中踩过的十六个坑一个一个列出来包括 Android WebView 的版本兼容、Supabase 的权限配置、文件上传的 content:// 协议处理、进度条卡死、依赖解析失败这些具体问题。如果你也是那种接了小项目、想快速把东西做出来上线、又不想在环境配置上浪费太多时间的开发者这篇内容应该能帮你省下不少试错成本。WorkBuddy 这个工具本身定位是轻量级的开发协作环境它和 CodeBuddy 的区别在于更偏向项目管理和快速原型搭建而不是纯粹的代码补全。我后面会详细说这两者的差异以及为什么在这个项目里我选了 WorkBuddy 而不是别的方案。整个项目的技术栈是这样的前端用 HTML、CSS 和原生 JavaScript 写页面通过 WebView 嵌入到 Android 和 iOS 的壳里后端用 Supabase 做数据库、认证和文件存储开发环境用 WorkBuddy 来管理任务、记录进度和协调前后端接口。这个组合的好处是上手快、成本低、不需要自己维护服务器缺点也很明显就是 WebView 的兼容性问题和 Supabase 的权限规则需要花时间调。下面我按阶段来说。2. 第一阶段需求拆解与技术选型2.1 先想清楚哪些功能必须原生、哪些可以 Web 化拿到需求之后我做的第一件事不是写代码而是把功能列表拆成两类一类是必须调用原生能力的一类是纯 Web 就能搞定的。这个判断直接决定了后面 WebView 要开放多少权限也决定了整个项目的复杂度。必须原生的部分包括相机调用签到时要拍照、文件选择上传活动素材、本地存储缓存用户登录状态、以及分享功能把活动链接分享到社交平台。这些在 Android 和 iOS 上都有对应的原生 APIWebView 里虽然也能通过 input 标签触发部分功能但体验和兼容性都不太稳定。纯 Web 能搞定的部分包括报名表单、活动列表、签到记录展示、用户管理后台。这些就是普通的页面交互用 HTML 加 JavaScript 写完之后直接塞进 WebView 就能跑。我当时的判断是原生部分只做最薄的壳把相机、文件、存储、分享这四个能力封装成 JavaScript 接口暴露给 WebView剩下的全部用 Web 实现。这样做的好处是业务逻辑只写一遍双端共用后期改需求也不用两边同步改。2.2 WorkBuddy 和 CodeBuddy 到底选哪个这两个工具我都用过一段时间简单说一下我的理解。CodeBuddy 更偏向代码层面的辅助比如帮你补全函数、生成注释、检查语法错误适合那种已经有明确代码结构、需要提高编码效率的场景。WorkBuddy 则更偏向项目层面的管理它可以帮你拆解任务、跟踪进度、记录每个阶段的产出还能把前后端的接口约定整理成文档。这个项目里我选 WorkBuddy 的原因是我一个人要同时兼顾前端页面、原生壳、后端配置和上线部署如果没有一个地方把任务和进度管起来很容易乱。WorkBuddy 的任务看板功能让我每天早上打开就知道今天该做什么哪些接口还没联调哪些页面还没适配。另外它的 skill 机制可以让我把一些重复性的操作比如生成 Supabase 的建表语句、检查 WebView 的版本兼容性固化成可复用的流程省了不少时间。如果你只是单纯想提高写代码的速度CodeBuddy 可能更合适但如果你像我一样需要管整个项目的节奏WorkBuddy 会更顺手。当然这两个工具并不冲突我后来也在 WorkBuddy 里集成了 CodeBuddy 的代码补全能力算是各取所长。2.3 Supabase 做后端的取舍选 Supabase 的理由很简单免费额度够用、自带认证和数据库、支持实时订阅、有现成的 JavaScript SDK。对于这种小团队内部工具来说自己搭服务器完全是浪费用 Supabase 可以让我把精力集中在业务逻辑上。但 Supabase 也有它的坑。首先是权限规则默认的行级安全策略非常严格如果不手动配置前端根本读不到数据。其次是文件存储的路径管理如果命名规则没设计好后期找文件会很痛苦。还有就是实时订阅的频道管理订阅多了之后性能会下降。这些我在后面都会详细说。3. 第二阶段WorkBuddy 环境搭建与项目初始化3.1 安装 WorkBuddy 和配置开发环境WorkBuddy 的安装过程不算复杂但有几个地方需要注意。首先是系统缓存目录的设置默认路径在 C 盘如果你的 C 盘空间紧张最好在安装完成后第一时间改到其他盘。我当时的 C 盘只剩不到 10G装完之后直接红了后来在设置里把缓存目录改到 D 盘才缓过来。安装完成之后我建议先创建一个空项目把目录结构定下来。我的结构是这样的project-root/ app/ # 原生壳代码 android/ # Android 项目 ios/ # iOS 项目 web/ # Web 页面代码 pages/ # 页面 assets/ # 静态资源 js/ # 脚本 supabase/ # 后端配置 migrations/ # 数据库迁移 functions/ # 边缘函数 docs/ # 接口文档和进度记录这个结构的好处是前后端分离清晰原生壳和 Web 页面各自独立Supabase 的配置也单独放一块。WorkBuddy 的任务看板可以按这个结构来拆分任务比如“完成 web/pages 下的报名表单页面”、“配置 supabase/migrations 里的用户表”。3.2 Android 项目初始化的几个关键配置Android 项目我用的是 Android Studio版本是 2023 年的稳定版。创建项目的时候选 Empty Views Activity语言选 Kotlin最低 SDK 版本我设的是 API 24Android 7.0目标 SDK 是 API 34。为什么最低选 24因为再低的版本 WebView 内核太老很多现代 JavaScript 特性不支持适配成本太高。创建完项目之后第一件事是在AndroidManifest.xml里加权限uses-permission android:nameandroid.permission.INTERNET / uses-permission android:nameandroid.permission.CAMERA / uses-permission android:nameandroid.permission.READ_EXTERNAL_STORAGE / uses-permission android:nameandroid.permission.WRITE_EXTERNAL_STORAGE /然后在build.gradle里加上 WebView 的依赖。这里有个坑Android 的 WebView 版本是跟系统绑定的不同设备上的版本差异很大。我后面会专门讲怎么检测和处理这个问题。3.3 iOS 项目初始化的注意事项iOS 这边我用的是 Xcode创建项目的时候选 App 模板界面用 Storyboard语言选 Swift。最低部署版本我设的是 iOS 14因为再低的版本市场份额已经很小了没必要花精力适配。iOS 的 WebView 用的是 WKWebView比 Android 的 WebView 性能好很多兼容性问题也少。但有一个地方需要注意iOS 对本地文件的访问限制比较严如果 Web 页面要加载本地资源必须把资源放到 bundle 里或者通过本地服务器的方式提供。我当时的做法是把 Web 页面打包成静态资源直接嵌入 bundle这样加载速度最快也不依赖网络。4. 第三阶段WebView 容器与 Web 页面的桥接4.1 Android WebView 的版本检测与兼容处理这是整个项目里最折腾的部分。Android 的 WebView 内核版本跟系统版本、厂商定制、用户是否更新过都有关系。我在测试机上遇到过 WebView 版本只有 60 多的情况很多 ES6 语法都不支持页面直接白屏。我的解决方案是在原生壳启动的时候先检测 WebView 版本如果低于某个阈值就提示用户升级或者降级加载一个兼容版本的页面。检测的代码大概是这样val webViewPackageInfo WebView.getCurrentWebViewPackage() val version webViewPackageInfo?.versionName ?: unknown拿到版本号之后我设了一个阈值如果主版本号低于 80就加载web/compat/目录下的兼容页面这个页面用的是 ES5 语法和 polyfill牺牲一些性能换取兼容性。如果高于 80就加载正常的页面。另外我还发现一个现象有些国产厂商的 WebView 内核虽然版本号很高但实际上阉割了一些特性比如不支持某些 CSS 属性或者 JavaScript API。这种情况只能靠真机测试来发现模拟器上跑不出来。4.2 JavaScript 与原生代码的互相调用WebView 和原生代码的通信是双向的。Web 页面需要调用原生的相机、文件选择、分享功能原生代码也需要把一些状态比如登录 token、设备信息传给 Web 页面。Android 这边的做法是创建一个 JavaScript 接口类class NativeBridge(private val context: Context) { JavascriptInterface fun openCamera(): String { // 调用相机返回图片路径 } JavascriptInterface fun getDeviceInfo(): String { // 返回设备信息 JSON } }然后通过webView.addJavascriptInterface(NativeBridge(this), NativeBridge)注册。Web 页面里就可以用window.NativeBridge.openCamera()来调用。iOS 这边用的是WKScriptMessageHandler原理类似但写法不同。需要注意的是iOS 的evaluateJavaScript必须在主线程调用否则会崩溃。这里有个坑Android 的JavascriptInterface注解在 API 17 以下是不需要的但在 API 17 以上必须加否则方法不会被暴露。我一开始漏了这个注解调试了半天才发现。4.3 文件上传的 content:// 协议处理Android 从 7.0 开始引入了 FileProvider文件选择器返回的 URI 是content://开头的而不是传统的file://。WebView 里的 input 标签拿到这个 URI 之后如果直接传给后端后端是解析不了的必须先转成真实文件路径或者直接读取成字节流。我的做法是在原生层拦截文件选择的结果把content://URI 转成文件路径然后再传给 Web 层。转换的代码大概是这样fun getFilePathFromUri(context: Context, uri: Uri): String? { val projection arrayOf(MediaStore.Images.Media.DATA) val cursor context.contentResolver.query(uri, projection, null, null, null) cursor?.use { if (it.moveToFirst()) { val columnIndex it.getColumnIndexOrThrow(MediaStore.Images.Media.DATA) return it.getString(columnIndex) } } return null }但这个方法在 Android 10 以上又失效了因为分区存储的限制。后来我改成了直接把文件读成字节流通过 Base64 编码传给 Web 层虽然效率低一点但兼容性最好。5. 第四阶段Supabase 后端配置与数据同步5.1 数据库表设计与行级安全策略Supabase 的数据库就是 PostgreSQL建表没什么特别的但行级安全策略RLS一定要提前设计好。默认情况下RLS 是关闭的但一旦开启所有没有策略的表都会拒绝所有访问。我的表结构大概是这样的表名用途关键字段users用户信息id, phone, name, roleevents活动信息id, title, date, locationregistrations报名记录id, user_id, event_id, statuscheckins签到记录id, user_id, event_id, photo_urlRLS 策略我设了三条用户只能读自己的报名记录、只能写自己的签到记录、管理员可以读所有记录。策略的写法大概是create policy users can read own registrations on registrations for select using (auth.uid() user_id);这里有个坑auth.uid()只有在用户登录之后才有值如果用户没登录这个策略会直接拒绝访问。所以登录流程必须在所有数据操作之前完成。5.2 实时订阅的频道管理与性能优化Supabase 的实时订阅功能很好用但订阅多了之后性能会明显下降。我一开始给每个页面都开了独立的订阅频道结果同时打开几个页面之后消息延迟变得很高。后来我改成了按业务模块合并频道报名相关的订阅合并成一个频道签到相关的合并成另一个。每个频道里只订阅必要的表不相关的表不订阅。这样改完之后消息延迟从原来的两三秒降到了几百毫秒。另外实时订阅的回调函数里不要做太重的操作比如大量的 DOM 更新或者网络请求。我的做法是收到消息之后先存到一个队列里然后用requestAnimationFrame批量更新 UI这样不会阻塞主线程。5.3 文件存储的路径规划与访问控制Supabase 的存储桶默认是私有的需要生成签名 URL 才能访问。如果活动照片比较多每次都生成签名 URL 会很慢。我的做法是把活动照片放在一个公开桶里但文件名用随机字符串避免被猜到。用户头像这种敏感一点的放在私有桶里按需生成签名 URL。路径规划我用的规则是{bucket}/{event_id}/{user_id}/{timestamp}.jpg。这样按活动 ID 就能找到所有相关照片按用户 ID 就能找到某个用户的所有上传记录。后期清理数据的时候也方便直接按前缀删除就行。6. 第五阶段上线前的测试与问题排查6.1 常见问题速查表这个表格是我在测试阶段整理出来的基本上覆盖了八成以上的问题问题现象可能原因解决方法页面白屏WebView 版本过低检测版本降级加载兼容页面文件上传失败content:// URI 未转换原生层转成字节流或真实路径数据读不到RLS 策略未配置检查策略确保 auth.uid() 有值实时消息延迟订阅频道过多合并频道减少订阅数量依赖解析失败Gradle 版本不匹配检查 build.gradle 和 gradle-wrapper进度条卡死主线程阻塞把耗时操作放到子线程相机打不开权限未申请动态申请相机权限分享失败分享接口未注册检查 AndroidManifest 和 Info.plist6.2 依赖解析失败的排查思路could not resolve all task dependencies这个错误我在项目里遇到过两次。第一次是因为 Gradle 版本和 Android Gradle Plugin 版本不匹配第二次是因为仓库地址配置错了。排查的思路是这样的先看错误信息里具体是哪个依赖解析不了然后去 Maven 仓库确认这个依赖是否存在、版本号是否正确。如果依赖存在就检查build.gradle里的仓库配置确保google()和mavenCentral()都在。如果还是不行就清理缓存重新同步./gradlew clean ./gradlew --refresh-dependencies还有一个容易被忽略的点有些依赖需要特定的 Gradle 版本才能解析如果 Gradle 版本太低会直接报解析失败。我后来把 Gradle 升到了 8.0问题就没了。6.3 进度条卡死的几种情况进度条卡死通常是因为主线程被阻塞了。Android 里所有 UI 操作都必须在主线程执行如果主线程在等网络请求或者做大量计算进度条就不会动。我的做法是把所有耗时操作都放到子线程用Coroutine或者Thread都行完成之后再切回主线程更新 UI。另外进度条的更新频率不要太高每 100 毫秒更新一次就够了太频繁反而会卡。还有一种情况是进度条的逻辑本身有问题比如进度值一直不增加或者增加到了 100 但没触发完成回调。这种就是代码 bug 了需要加日志慢慢排查。7. 第六阶段上线部署与后续维护7.1 Android 打包与签名Android 打包用的是./gradlew assembleRelease但在这之前需要配置签名。签名文件用 Android Studio 的生成工具创建就行创建完之后在build.gradle里配置signingConfigs { release { storeFile file(release.keystore) storePassword your_password keyAlias your_alias keyPassword your_password } }这里有个坑签名文件千万不要提交到代码仓库密码也不要硬编码在build.gradle里。我的做法是把密码放在local.properties里这个文件默认不会被提交。7.2 iOS 打包与分发iOS 打包需要 Apple 开发者账号个人账号一年 99 美元。打包流程比 Android 复杂一些需要配置证书、描述文件、App ID 这些。我建议用 Xcode 的自动管理签名功能省去手动配置的麻烦。分发方式我选的是 Ad Hoc因为用户量不大不需要上架 App Store。Ad Hoc 需要收集用户的设备 UDID然后生成对应的描述文件。用户量大的话可以考虑 TestFlight但审核流程会慢一些。7.3 上线后的监控与迭代上线之后我加了一个简单的错误监控用 Supabase 的边缘函数接收前端上报的错误日志存到数据库里。每周看一次有异常就及时修。迭代方面因为 Web 页面是动态加载的改完之后用户下次打开就能看到新版本不需要重新发版。原生壳的改动才需要重新打包。所以我把大部分业务逻辑都放在 Web 层原生壳尽量保持稳定减少发版频率。8. 十六个坑的完整清单与避坑建议前面分散着讲了一些坑这里我集中列一下方便你对照排查WorkBuddy 缓存目录默认在 C 盘安装完第一时间改到其他盘否则 C 盘很快满。Android WebView 版本差异大启动时检测版本低于阈值加载兼容页面。JavascriptInterface 注解漏加API 17 以上必须加否则方法不暴露。content:// URI 直接传后端必须先转成文件路径或字节流。Android 10 分区存储限制getFilePathFromUri 失效改用字节流方案。Supabase RLS 默认拒绝所有访问建表后立即配置策略。auth.uid() 未登录时为空确保登录流程在所有数据操作之前。实时订阅频道过多按业务模块合并频道减少订阅数量。实时回调里做重操作用队列加 requestAnimationFrame 批量更新。存储桶默认私有公开资源放公开桶敏感资源按需生成签名 URL。Gradle 版本与 AGP 不匹配升级 Gradle 到 8.0 以上。仓库地址配置不全确保 google() 和 mavenCentral() 都在。主线程阻塞导致进度条卡死耗时操作放子线程完成后切回主线程。签名文件提交到仓库密码放 local.properties签名文件加 .gitignore。iOS 本地资源访问限制Web 页面打包进 bundle 或走本地服务器。原生壳频繁发版业务逻辑放 Web 层原生壳保持稳定。这十六个坑里最耗时间的是 WebView 版本兼容和 Supabase 权限配置这两个加起来占了我整个项目调试时间的一半以上。如果重来一次我会在项目开始之前就先做这两块的预研而不是等到出了问题再临时找方案。9. 一些个人体会和后续扩展思路这个项目做完之后我最大的感受是小项目用轻量级方案确实能省很多时间但省下来的时间往往会花在兼容性和权限配置上。WorkBuddy 加 WebView 加 Supabase 这个组合适合那种功能不复杂、用户量不大、工期紧的场景。如果项目再大一点比如需要复杂的离线同步或者高性能的图形渲染这个方案就不太够了还是得走原生开发。后续如果要扩展我考虑过几个方向。一是把 Web 页面改成 PWA这样用户可以直接在浏览器里用不需要装 App。二是把 Supabase 的边缘函数用起来把一些敏感操作放到服务端减少前端的安全风险。三是加一个简单的管理后台用 Supabase 的 Table Editor 或者自己写一个 Web 页面都行。最后分享一个小技巧如果你也在用 WebView 加载本地页面可以在开发阶段开启 WebView 的调试模式这样可以用 Chrome 的开发者工具直接调试 Web 页面比在原生代码里打日志方便得多。Android 上通过WebView.setWebContentsDebuggingEnabled(true)开启iOS 上在 Safari 的设置里开启 Web Inspector 就行。这个技巧帮我省了很多排查时间强烈建议试试。