1. 从零到上线，为什么我选了 WorkBuddy 这条路线
去年年底我接了个私活，帮一个做线下培训的朋友搭一套内部管理工具。需求听起来不复杂：老师排课、学员签到、课时统计、简单报表，外加一个给家长看进度的小程序端。预算有限，工期给了六周，团队就我一个人。这种项目最考验的不是技术深度，而是选型判断——用什么工具能在最短时间内把东西做出来，还得保证能真正上线跑起来，而不是停在演示阶段。
我前后试过三条路。第一条是纯原生 Android 加后端自建，光环境搭建和基础框架就吃掉一周，果断放弃。第二条是低代码平台，拖拽确实快，但一到自定义业务逻辑就卡壳，导出部署还要额外付费，长期看是个无底洞。第三条就是 WorkBuddy，配合 Supabase 做数据层，Android 端用 WebView 做混合容器。最终这套组合让我在五周内交付了可用版本，上线后跑了三个月，除了两次小问题，整体稳定。
这篇内容我想把整个过程拆开讲清楚。不是那种"三步搞定"的爽文，而是把六个开发阶段里真实踩过的十六个坑一个个摆出来，包括每个坑的排查思路和最终解法。适合谁看？如果你正在用 WorkBuddy 做 App 开发，或者打算用 WebView 加 Supabase 这套组合拳，又或者你只是想知道一个能上线的 App 到底要经历哪些环节，这篇应该能帮你省下不少试错时间。关键词里的 WorkBuddy、Android、WebView、Supabase 这几个词，基本就是全文的主线。
先说结论性的判断：WorkBuddy 的价值在于它把项目脚手架、构建流程和部分后端能力做了整合，让你不用从零配置 Gradle、不用手写一堆样板代码。但它不是银弹，很多边界情况需要你自己处理。Supabase 作为后端，免费额度对中小项目够用，实时订阅和行级安全策略是它的亮点。WebView 则是把 Web 技术栈塞进原生壳里的桥梁，用好了开发效率翻倍，用不好就是性能噩梦。这三者怎么配合，后面会一步步展开。
2. 阶段一：环境搭建与项目初始化，那些文档没写的细节
2.1 WorkBuddy 安装后第一件事不是写代码
很多人装完 WorkBuddy 就急着新建项目，我建议先花二十分钟做三件事。第一，确认你的 JDK 版本。WorkBuddy 对 JDK 版本有隐性要求，我一开始用的 JDK 17，构建时一直报一个关于字节码版本的模糊错误，换成 JDK 11 后问题消失。这个坑的隐蔽之处在于错误信息完全不提 JDK，只说什么"unsupported class file major version"，新手很容易往依赖冲突方向查。
第二，检查 Android SDK 的路径配置。WorkBuddy 有时不会自动识别系统里已装的 SDK，需要手动在设置里指定。如果路径里有中文或空格，构建大概率失败。我见过一个案例，SDK 装在"Program Files"下面，空格导致 Gradle 解析路径时截断，报错信息指向一个根本不存在的目录。
第三，把 Gradle 的镜像源配好。默认源在国内网络环境下拉依赖经常超时，换成国内镜像后构建时间从十几分钟降到两三分钟。这个配置在 WorkBuddy 的项目级配置文件里改，具体位置每个版本略有差异，建议直接搜"WorkBuddy Gradle 镜像"找对应版本的说明。
提示：环境搭建阶段遇到的报错，九成以上是版本不匹配或路径问题，不要一上来就怀疑代码。
2.2 项目结构怎么规划才不会被自己坑
WorkBuddy 生成的项目结构有它自己的约定，我建议不要随意打乱。核心目录大致分几块：源码目录、资源目录、配置文件目录、构建脚本目录。我的经验是把业务代码按功能模块分包，而不是按类型分包。什么意思？就是不要建一个巨大的"activities"包和一个巨大的"models"包，而是按"排课""签到""报表"这样的业务维度分，每个模块里再放自己的页面、数据模型、网络请求。
这样做的理由很实际：当你三个月后回来改某个功能，你能一眼定位到相关代码全在哪个包里，而不是在十几个包之间跳来跳去。我第一个版本就是按类型分的，后来加需求时找代码找得想砸键盘，第二个版本重构后才舒服。
另外，配置文件里的版本号管理要统一。WorkBuddy 有些版本会把依赖版本散落在多个文件里，改一个地方忘了另一个，就会出现"明明改了版本但构建用的还是旧的"这种诡异现象。建议把所有版本号抽到一个统一的配置块里管理。
2.3 第一个能跑起来的空壳，比想象中重要
不要小看"能跑起来"这件事。我建议在写任何业务代码之前，先确保一个最简单的页面能在真机上打开。这一步验证的是整条链路：WorkBuddy 构建、Android 打包、真机安装、启动。任何一环有问题，现在发现比写完一堆代码后发现要好得多。
真机调试时，USB 调试权限、驱动安装这些老生常谈的问题就不展开了。重点说一个 WorkBuddy 特有的：它的调试模式有时和 Android Studio 的调试端口冲突，如果你两个工具同时开着，可能出现设备识别不到的情况。关掉一个再试。
3. 阶段二：WebView 容器的搭建与那些让人抓狂的兼容问题
3.1 为什么用 WebView 而不是纯原生
这个问题我被问过很多次。纯原生性能好、体验流畅，但开发速度慢，尤其是页面多、交互复杂的项目。WebView 的本质是在原生 App 里嵌入一个浏览器内核，用 HTML、CSS、JavaScript 写界面，原生只负责容器和部分能力调用。对于我这种一个人扛全栈的场景，WebView 让前端和移动端用同一套代码，效率提升非常明显。
代价是什么？性能和兼容性。WebView 的渲染性能不如原生，复杂动画会卡。更麻烦的是不同 Android 版本、不同厂商的 WebView 内核版本差异巨大，同一个页面在这台机器上正常，换一台就白屏。这就是为什么关键词里会出现"webview 历史版本合集"这种搜索词——大家都在找特定版本的兼容方案。
我的策略是：核心交互用原生写，展示类、表单类、列表类页面用 WebView。这样既保证了关键路径的流畅，又享受了 Web 开发的效率。
3.2 WebView 初始化时必须设置的几个参数
默认的 WebView 配置几乎不能用，必须手动调整。以下是我实测下来必须设置的几项：
| 配置项 | 作用 | 不设置的后果 |
|---|---|---|
| JavaScript 开关 | 允许执行 JS | 页面完全没反应 |
| DOM Storage | 允许本地存储 | 登录状态丢失 |
| 混合内容模式 | 允许 HTTPS 页面加载 HTTP 资源 | 图片、接口加载失败 |
| 缓存策略 | 控制缓存行为 | 更新后用户看到旧页面 |
| 缩放控制 | 禁止用户缩放 | 页面布局错乱 |
混合内容这一项特别容易踩坑。现在主流是 HTTPS，但很多老接口还是 HTTP，如果不开混合内容模式，这些请求会被直接拦截，而且报错信息很隐晦，只会在控制台里显示一行警告，页面上表现为数据加载不出来。
3.3 页面加载白屏的排查链路
白屏是 WebView 开发里最高频的问题，我总结了一套排查顺序，基本能覆盖九成情况。
第一步，看是不是 JS 报错。在 WebView 里开启远程调试，用电脑上的浏览器开发者工具连上去看控制台。这一步能发现大部分问题，比如某个 API 在当前内核版本不支持。
第二步，看是不是资源加载失败。检查网络请求，确认 HTML、CSS、JS 文件都正常返回。有时候是路径问题，打包后资源路径变了，本地测试正常线上就白屏。
第三步，看是不是内核版本太低。老版本 Android 的 WebView 内核可能不支持某些 ES6+ 语法，比如可选链、空值合并。解决办法是构建时做语法降级，或者引入 polyfill。
第四步，看是不是渲染时机问题。有些页面在 DOM 还没准备好时就执行了操作，导致报错。把初始化逻辑放到页面加载完成事件里。
我遇到过一个特别隐蔽的：页面在 WiFi 下正常，在移动网络下白屏。查了半天发现是移动网络下 DNS 解析慢，某个同步加载的脚本超时了。改成异步加载后解决。
3.4 原生与 WebView 的通信设计
WebView 和原生之间的通信是混合开发的核心。常见方案有两种：一种是原生注入对象，Web 端通过约定的接口调用；另一种是 Web 端通过 URL 跳转触发原生拦截。前者更规范，后者更灵活但容易乱。
我推荐用注入对象的方式，并且把接口设计得清晰一点。比如定义一个统一的消息通道，Web 端发消息时带上类型和数据，原生端根据类型分发处理。这样以后加新功能不用改通信层，只加处理逻辑就行。
要注意的是，注入的对象在页面刷新后会丢失，需要在每次页面加载时重新注入。这个坑我踩过，调试时页面不刷新一切正常，一刷新所有原生调用都失效，查了好久才发现是注入时机的问题。
4. 阶段三：Supabase 作为后端，从建表到实时订阅
4.1 为什么选 Supabase 而不是自己写后端
自己写后端意味着要处理服务器、数据库、接口、鉴权、部署、监控这一整套。对一个人来说，这些工作量可能比业务逻辑本身还大。Supabase 把这些都打包好了，你只需要建表、写查询、配权限，剩下的它帮你管。
它的核心能力有几块：PostgreSQL 数据库、自动生成的 REST 和实时接口、行级安全策略、用户认证、文件存储。对中小项目来说，免费额度基本够用。我那个培训管理项目，几百个用户，每天几千次请求，跑在免费额度里毫无压力。
但要注意，Supabase 不是万能的。复杂的事务逻辑、高性能计算、自定义的业务规则，还是得自己写。我的做法是把简单的增删改查交给 Supabase，复杂的业务逻辑放在客户端或者用它的边缘函数处理。
4.2 建表时最容易忽略的几件事
第一，主键类型。Supabase 默认用 UUID，这没问题，但如果你要和外部系统对接，用自增整数可能更方便。我一开始全用 UUID，后来和微信端的用户 ID 对接时，类型转换搞得头大。
第二，时间戳字段。一定要加创建时间和更新时间，并且设置默认值和自动更新。没有这两个字段，后期排查问题时会很痛苦，你根本不知道某条数据是什么时候变成现在这样的。
第三，索引。Supabase 不会自动给外键加索引，查询慢的时候要自己检查。我有个查询一开始要两秒，加了个索引后降到几十毫秒。
第四，行级安全策略。这是 Supabase 的精髓，也是最容易配错的地方。默认情况下，如果不开策略，数据是公开的。我见过有人上线后发现所有用户都能看到别人的数据，就是因为忘了配策略。正确做法是每条策略都明确"谁能读、谁能写、条件是什么"。
4.3 实时订阅的坑与优化
Supabase 的实时订阅很香，数据一变客户端立刻收到通知。但它有几个坑。
第一个坑是订阅数量限制。免费版对同时订阅的频道数有限制，如果你给每个页面都开一个订阅，很快就超了。我的做法是全局维护一个订阅管理器，按需订阅、用完释放。
第二个坑是断线重连。网络切换时订阅会断，需要监听状态并自动重连。Supabase 的客户端库有内置重连，但默认参数不一定适合移动网络，建议调一下重连间隔和超时时间。
第三个坑是数据量。订阅推送的是变更后的完整记录，如果记录很大，流量消耗可观。对于大字段，建议拆表或者只订阅关键字段。
4.4 认证与用户体系
Supabase 自带认证系统，支持邮箱、手机号、第三方登录。我用的是手机号加验证码的方式，因为目标用户是家长和老师，邮箱使用率低。
配置时要注意几点：验证码的有效期和发送频率限制要设合理，太短用户来不及输入，太长有安全风险。第三方登录的回调地址要配全，包括测试环境和生产环境。用户资料的扩展字段建议单独建一张表关联，不要往认证表里塞业务数据。
还有一个容易忽略的：用户注销和账号删除。合规要求下，用户应该能删除自己的账号和数据。Supabase 的认证删除不会自动清理业务表里的数据，需要自己写级联删除逻辑。
5. 阶段四：业务功能开发中的十六个坑实录
5.1 前八个坑：从排课到签到
坑一：日期时间处理。客户端、数据库、服务端三者的时区不一致，导致排课时间错乱。解决办法是统一用 UTC 存储，展示时再转本地时区。
坑二：并发签到。多个老师同时给同一个学员签到，产生重复记录。解决办法是用数据库的唯一约束兜底，而不是只靠客户端判断。
坑三：列表分页。数据量大了以后一次性加载全部会卡死。解决办法是用游标分页而不是偏移分页，避免数据变动时的重复和遗漏。
坑四：图片上传。直接传原图又慢又费流量。解决办法是客户端压缩后再传，Supabase 存储支持图片转换，可以生成缩略图。
坑五：表单校验。只在客户端校验不够，服务端也要校验。我见过有人绕过客户端直接调接口，插入了非法数据。
坑六：错误提示。技术错误直接抛给用户看不懂。解决办法是统一错误码和友好提示的映射。
坑七：离线处理。网络不好时操作失败，用户重复点击。解决办法是加防抖和操作队列，网络恢复后自动重试。
坑八：数据导出。报表导出 Excel 时中文乱码。解决办法是加 BOM 头或者用正确的编码格式。
5.2 后八个坑：从报表到上线
坑九：统计查询慢。随着数据增长，报表查询越来越慢。解决办法是预计算，把统计结果定时算好存起来，查询时直接读。
坑十：权限越界。老师能改别的老师的数据。解决办法是行级安全策略里严格按用户 ID 过滤。
坑十一：缓存不一致。改了数据但页面还是旧的。解决办法是变更后主动刷新缓存，或者用实时订阅自动更新。
坑十二：内存泄漏。WebView 页面切换后没释放，内存持续增长。解决办法是在页面销毁时清理 WebView，移除所有引用。
坑十三：启动速度。冷启动要好几秒。解决办法是延迟初始化非必要组件，用启动页过渡。
坑十四：崩溃恢复。App 崩溃后用户数据丢失。解决办法是关键操作本地暂存，重启后恢复。
坑十五：版本更新。用户不更新导致新旧版本接口不兼容。解决办法是接口做版本控制，旧版本继续可用一段时间。
坑十六：应用体积。打包出来一百多兆。解决办法是开启资源压缩、移除无用依赖、用 App Bundle 分发。
这十六个坑里，我觉得最值得展开的是坑二和坑十，因为它们涉及数据一致性和安全，出问题后果最严重。并发签到那个，我当时的解法是在数据库层加唯一索引，字段是学员 ID 加日期，这样即使客户端重复提交，数据库也会拒绝第二条。权限那个，行级安全策略写好后一定要用不同角色的账号实测，不要想当然。
6. 阶段五：测试、打包与上线的完整流程
6.1 测试阶段该测什么
功能测试是基础，但光测功能不够。我建议重点测这几类：弱网环境下的表现、不同 Android 版本的表现、不同屏幕尺寸的表现、后台切换回来的状态恢复、权限被拒绝时的降级处理。
弱网测试可以用工具模拟，重点看加载中的提示是否友好、超时是否有重试、失败是否有明确原因。Android 版本测试至少要覆盖 8.0 到最新版，因为 WebView 内核差异主要在这个区间。屏幕尺寸测试关注布局是否错乱，尤其是平板和折叠屏。
6.2 打包时的配置要点
签名配置要保管好，丢了就没法更新已上线的应用。建议把签名文件加密备份，密码单独记录。
混淆配置要仔细，有些反射调用的类不能被混淆，否则运行时报找不到类。WorkBuddy 生成的混淆规则是基础版，业务相关的要自己补。
多渠道打包如果不需要就关掉，能省不少构建时间。需要的话，用 WorkBuddy 的多渠道配置，不要手动改。
6.3 上线后的监控与迭代
上线不是终点。要配崩溃监控，第一时间知道哪里出问题。要配性能监控，知道启动时间、页面加载时间的变化趋势。要配用户反馈入口，让用户能方便地报告问题。
迭代节奏上，我建议小步快跑。每次更新解决一两个问题，不要攒一大堆一起发。这样出问题时容易定位，回滚也方便。
7. 阶段六：一份可复用的经验清单
7.1 选型决策的几条原则
第一，优先选能减少你工作量的工具，而不是功能最多的工具。功能多意味着学习成本和维护成本高。
第二，优先选社区活跃的工具。遇到问题能搜到答案，比官方文档写得漂亮更重要。
第三，优先选能平滑迁移的方案。万一工具不行了，换起来不至于推倒重来。
第四，不要为了用新技术而用新技术。能解决问题的就是好技术。
7.2 给 WorkBuddy 定几条规则
如果你团队多人用 WorkBuddy，建议定几条统一规则，避免各写各的。比如：项目结构统一按业务分包、依赖版本统一管理、代码风格统一配置、提交信息统一格式。这些规则定下来后，协作效率会明显提升。
7.3 我个人的几条心得
第一，文档要边做边写，不要等做完再补。补的时候很多细节已经忘了。
第二，遇到问题先记录，再解决。记录的过程往往能帮你理清思路，有时候记着记着就想到解法了。
第三，不要追求一次完美。先跑通，再优化。我第一个版本很多地方写得很糙，但能上线，后面慢慢改。
第四，留好回滚方案。每次上线前想清楚，如果出问题怎么退回去。
这套组合拳打下来，我最大的感受是：能上线的 App 和能跑的 Demo 之间，差的不是技术难度，而是对细节的处理。WorkBuddy 帮你省掉了环境配置和构建的麻烦，Supabase 帮你省掉了后端的麻烦，WebView 帮你省掉了跨端开发的麻烦，但业务逻辑、兼容性、安全性、性能这些，还是得自己一点点抠。十六个坑听起来多，但真正踩过一遍之后，你会发现它们其实都是同一类问题的不同表现——对边界情况的考虑不足。把边界情况想全了，坑自然就少了。
