移动端技术栈选型与关键优化：为什么这样选、踩过哪些坑
对照本 App 的真实工程，讲清一人团队为什么选 Next.js 静态导出 + Capacitor 混合架构、为什么用 Pyodide/WASM 在端内跑 Python、AI 为什么走后端网关，以及为移动端真机体验做过的一批关键底层优化
- 能对比原生/跨端/混合/H5 几条路线并说明本项目选型理由
- 理解 Pyodide(WASM) 在 Worker 内运行 Python 的机制与取舍
- 说清 AI 后端网关、流式输出与 TTS 的链路设计
- 掌握一批移动端真机关键优化（键盘、权限、看门狗、滚动条、缓存、合成层）
技术选型的第一性问题：在你的约束下，什么是最优解
技术栈从来没有“最好”，只有“在给定约束下最合适”。本项目的约束非常具体：一个人开发、要同时覆盖安卓安装包与 iOS 浏览器 H5、课程里要在手机上真正运行 Python、要内置 AI 对话与语音面试、还要能离线学习、快速迭代。下面所有选型都是围绕这些约束推导出来的，而不是因为某个框架“新”或“火”。
一、客户端路线：为什么是“静态导出 + Capacitor 混合”
五条路线在本项目约束下的对比
路线 开发效率 多端复用 端能力 离线 适配本项目原生 Swift/Kotlin双端 低(写两遍) 无 最强 强 一人团队产能不足React Native/Flutter 中 高 强 中 跑 Web 生态/Pyodide 不自然纯 H5/PWA 高 一套 弱 中 难上架、权限/键盘/文件受限Capacitor 混合(选用) 高 一套Web 中(桥) 强 Web 迭代+原生补系统能力小程序 中 锁定平台 中 弱 无法自由分发/跑 WASM 受限
最终选择混合架构：用 Next.js 把前端静态导出（SSG）成纯静态资源，同一份代码在安卓用 Capacitor 包成原生 APK、在 iOS 用 Safari 直接访问 H5；Web 负责快速迭代的课程、UI 与业务逻辑，原生层只负责 Web 做不到或体验差的部分——运行时权限（麦克风/摄像头）、edge-to-edge 键盘高度、状态栏与安全区、文件分享、版本更新、文本选择手柄等。这样既拿到 Web 的高迭代效率与多端一致性，又用原生补齐了系统能力，规避了“纯网页打包功能不足被商店驳回”的风险。
很多人瞧不上 WebView 套壳，问题其实不在技术，而在有没有划清 Web 与原生的边界。把一切都丢给网页、权限键盘卡顿全不管，那才叫偷懒，也确实会被驳回；而把高频变化的内容留给 Web、把系统级能力与体验兜底交给原生，并在两者之间设计稳定的桥接（CSS 变量、事件、插件），反而是中小团队商业落地性价比最高的架构。判断标准很简单：用户用起来是否和原生一样跟手、稳定——做到了，用户根本不关心你用什么技术。
二、为什么用 Pyodide/WASM 在端内跑 Python
课程要让学员在手机上真刀真枪写并运行 Python，有三条路：把代码发到后端执行——需要服务器算力、有安全风险、离线不可用、并发成本高；用 Skulpt 这类 JS 重写的 Python——只实现了语言子集，第三方库与现代语法支持弱；Pyodide：把 CPython 解释器本身编译成 WebAssembly，在浏览器/WebView 里得到一个几乎完整的 CPython。本项目选第三条（Pyodide），换来“零后端算力、零安全沙箱风险、离线可跑、与桌面一致”的体验，代价是首次加载体积与内存，于是用懒加载与 Worker 隔离来摊薄。
# 端内 Python 运行链路（见 lib/pyodide/executor.ts）
# 主线程 UI ──run(code)──▶ 单例 Web Worker
# Worker: import Pyodide(CPython→WASM) → 执行 → postMessage 回结果
# 双阶段看门狗: micropip 装包 60s 超时 / 单次执行 5s 超时
# 死循环/超时 → 终止并重启 Worker、清空命名空间,保证下一题环境干净
# stdin、matplotlib、第三方包按需加载,主线程全程不卡本项目把 Python 放进 Web Worker 里用 Pyodide 执行，最主要的好处是？
三、前端与状态：为什么是 Next + React + Tailwind + Framer Motion + Zustand
Next.js 提供路由、静态导出与一体化工程能力，构建期把每个课程页预渲染成静态 HTML，首屏快、可离线、可托管到任意静态服务器；React 负责组件化；Tailwind 用原子类配合一组 CSS 变量 token（颜色/间距/圆角/动效时长），让深色/浅色主题切换与全局视觉一致性变得可控；Framer Motion 用声明式方式处理面板、抽屉、列表动画，并尊重系统的“减少动态效果”设置；状态管理选 Zustand 而非 Redux——API 简洁、几乎无样板，配合 persist 中间件把学习进度自动序列化到 localStorage，启动时恢复。持久化结构带 version 字段和迁移函数，保证老用户升级后旧存档平滑兼容。
四、AI 链路：为什么必须有自己的后端网关
AI 能力看似“前端调一下接口”，但生产环境不能让 App 直连大模型：静态前端包会被下载、反编译，密钥写进去等于公开，会被盗刷。因此用 server.js 做一层网关，统一承担五件事——隐藏并轮换大模型密钥、按设备做限流与配额、对输入输出做内容安全审核、随时切换模型而不用发新版、把回答转成 SSE 分块流式输出实现“边生成边显示”。语音朗读则由独立的 TTS 服务经 Nginx 反代，点按即可播放并做了连读不串音的队列控制。
# AI/语音链路
# App ──/api/chat──▶ 自有网关(server.js) ──▶ 已备案大模型(密钥只在服务端)
# ▲ SSE 分块流式: token 到达即渲染,首字延迟最低
# App ──/tts?text=...──▶ TTS 服务 ──▶ audio/mpeg 流式朗读
# 网关同时负责: 限流 / 内容审核 / 多模型切换 / 设备同步 / 日志五、为移动端真机做过的一批“看不见但关键”的优化
真正拉开体验差距的，往往是这些真机上才暴露、教程里很少讲的底层细节，它们也是本项目反复打磨的重点：
关键优化清单（均来自真机踩坑）
1 软键盘: edge-to-edge 下 adjustResize 不缩 WebView、visualViewport 不变 → 原生监听 IME 高度,以 CSS 变量 --kb 推给前端避让(useKeyboardHeight)2 面试权限: Capacitor 共享 permissionListener,连续两次 getUserMedia 重复 grant 会抛 IllegalStateException → 共享单一麦克风流 + 原生重写 onPermissionRequest;无虚拟设备时麦克风/识别必须有失败兜底(voiceDown)3 运行安全: Worker 双阶段看门狗 + 死循环重启 + 清空命名空间4 加载性能: 静态导出 + 代码分割,Pyodide/Monaco/大组件按需懒加载, 服务器对 .wasm 返回正确 MIME(application/wasm) 才能流式编译5 滚动条: 原生 setVertical/HorizontalScrollBarEnabled(false) + CSS 全局 隐藏,仅 AI 对话区用高特异性类白名单保留细滚动条并支持闲置渐隐6 缓存与闪烁: H5 用 Service Worker 离线缓存;原生壳内反而主动注销 SW, 避免 skipWaiting 的 controllerchange 触发整页 reload 造成入场后闪屏7 渲染性能: 动画元素 translateZ(0) 独立合成层、毛玻璃面积克制,减少重绘
这是一个非常典型的混合开发坑：开启 edge-to-edge（setDecorFitsSystemWindows(false)）以实现沉浸式后，传统 adjustResize 不再压缩 WebView，visualViewport 在部分机型也不随键盘变化，前端拿不到可靠高度。靠 JS 猜测键盘高度在不同输入法、不同机型上必然翻车。可靠做法是在原生侧用 WindowInsets.Type.ime() 拿到精确键盘高度，转换成 CSS 像素通过桥接以 CSS 变量/事件实时推给前端，前端只负责按这个确定值避让。凡是系统才知道的信息，就向系统要，不要在网页里猜。
大模型密钥放在自有后端网关、而不是写进前端，最根本的原因是？
本节小结
本项目的技术栈是约束推导的结果：客户端选 Next.js 静态导出 + Capacitor 混合，一套 Web 代码同时出安卓 APK 与 iOS H5，原生只补系统能力；端内 Python 选 Pyodide 把 CPython 编译为 WASM、放进单例 Worker 并用双阶段看门狗保证不卡死、可恢复；前端用 Next/React/Tailwind/Framer Motion/Zustand 平衡效率、一致性与轻量，持久化带版本迁移；AI 走自有后端网关隐藏密钥、限流审核、流式输出，TTS 独立服务。关键真机优化包括原生测量键盘高度、共享麦克风流与重写权限回调、Worker 看门狗、懒加载与正确 WASM MIME、原生+CSS 双层治理滚动条、原生壳注销 SW 防入场闪屏、合成层与毛玻璃性能。选型不追新，只问“在我的约束下是否最稳、最省、体验最好”。
资深工程师加餐
底层原理 · 大厂视角 · 工程经验，点卡片展开
路由级代码分割与懒加载、图片懒加载并提供合适尺寸、输入用防抖、滚动用节流、超长列表用虚拟滚动；memo/useMemo/useCallback 不要无脑加，先用性能工具定位真实瓶颈。优化顺序永远是「测量 → 找到最贵的部分 → 针对性改 → 再测」。