把踩过的坑
记成能翻的页

声明 intent-filter 时 scheme 要小写，host 和 pathPrefix 是逐段比较的； 少一个斜杠就会静默匹配不上，只在系统日志里留一行 warning。

加上 autoVerify 之后，系统会去拉 /.well-known/assetlinks.json， 这个文件必须是 application/json 且不能跳转，否则验证状态会一直灰着。

自测最快的还是命令行：adb shell am start -a android.intent.action.VIEW -d "demo://host/path"， 比在 App 里反复点链接可靠得多。

MethodChannel 的回调默认在主线程，但原生侧如果在子线程里 invokeMethod， 不切回主线程就会出现“偶尔收不到”的玄学问题。包一层 runOnUiThread 就干净了。

另一个常被忽略的点：新增插件后热重载不会注册，必须完全重启进程， 否则抛 MissingPluginException，看起来像代码写错。

按 ABI 拆分能明显减小单个产物，但分发的文件变多，版本管理和用户选择成本都会上升； 全量包省事，代价是每个用户多下几十 MB。

资源压缩和混淆能再挤出一截，构建时间却会翻倍。 如果发布频率高，把这些放到 CI 的夜间任务里更划算。

还有一个容易忽略的：图标和字体的“全量打包”往往比代码更占体积，先查这里收益最明显。

心跳不要只依赖 TCP 层，应用层的 CONNECTED 帧才是真正可信的连接状态； 断线重连用指数退避，避免服务端重启瞬间被客户端打满。

订阅要在页面销毁时 unsubscribe； 重复订阅同一个 destination 会让回调触发多次，表现就是“消息重复”。

插件式租户拦截只对注册过的表生效，手写 SQL、视图、联表查询都能绕过去。 所以“加了拦截器就安全”是错觉，关键接口还是要在服务层再校验一次。

排查时最快的办法是把最终执行的 SQL 打出来，看有没有自动拼上租户条件，比读拦截器源码直观。

想支持断点续传，服务端必须回 Accept-Ranges 并正确处理 Range 请求， 返回 206 而不是整包 200，否则客户端进度会一直从 0 重来。

传完一定要做一次摘要校验。网络看起来正常、文件却少几十 KB 的情况，比想象中多。

fallbackToDestructiveMigration() 能让你在开发期少写一堆迁移脚本， 但它上线后意味着“升级即清库”。有本地缓存的场景，用户会直接丢数据，而且没有任何报错。

稳妥的做法是每次升级都补迁移，再用 MigrationTestHelper 跑一遍旧版本数据； 实在要临时用它，至少限定在 debug 构建里。

先开 Layout Inspector 的 recomposition 计数，能直观看到哪个组件在疯狂重组； 比凭感觉猜“是不是 state 放错位置了”快很多。

常见来源是 lambda 每次重建导致参数不稳定、以及把大对象塞进 remember 的依赖列表。 能 remember 就 remember，能用 derivedStateOf 就别直接算。

Upgrade 和 Connection 两个头必须透传，缺一个就会一直 400； 同时要把 proxy_read_timeout 调大，否则空闲一会儿就被断开，表现为“每分钟重连一次”。

排查时先看 nginx -T 有没有落到正确的 server 块——配置写在错的 server 里，改动是无效的。

字段上套函数、隐式类型转换、前导模糊匹配，这三类最容易让索引白建。 尤其是字符串列传了数字参数，MySQL 会做隐式转换，索引直接失效。

看执行计划别只看 type，rows 和 filtered 更能说明问题； 有时候 Using index 也未必是好事——覆盖索引扫全表一样慢。

还没推送：git reset --soft HEAD~1 把提交退回暂存区，改动一点不丢； 已经推送：用 git revert 生成一个反向提交，别对共享分支做 force push。

误提交了大文件的情况，光 revert 不够，历史里依然有大对象；要么用 filter-repo 重写， 要么就接受这个仓库会一直偏大。

这一版用 three.js 画了一层会呼吸的点阵，GSAP 负责入场和滚动出现。 库都放在本地 vendor/，不走 CDN，国内打开更快也不会被墙拖慢。

three.js 是动态 import() 的，只在首屏可见且用户没开“减少动效”时才加载； 手机端自动降低点数，页面切到后台就暂停渲染——好看不能以掉帧为代价。