下面是用TRAE WORK做伴学小程序开发，跑完完整流程之后复盘总结的23个坑。分为三类：前端坑（10个）、Web→小程序迁移坑（8个）、人与AI协作坑（5个）。每个坑标注了现象、原因、修法和教训。

一、前端坑（10个）

1. rich-text里ruby标签字号继承问题

现象： 古诗拼音正常显示，汉字全没了

原因： 外层字号设为零消除间隙，ruby标签内的汉字继承了字号0

修法： ruby标签显式设字号

教训： 小程序rich-text里每个层级都要显式设字号，别指望继承

2. wx:key语法错误

现象： 列表渲染报错

原因： 写了key而不是wx:key

修法： 改成wx:key

教训： 小程序的指令前缀不能丢

3. Canvas 2D API版本选择

现象： 新版Canvas 2D API坐标转换不稳定

原因： 不同基础库版本对新Canvas API支持不一致

修法： 改用旧版API，兼容性更好

教训： 小程序里API优先用旧版稳定的

4. tabBar页面跳转限制

现象： 从tabBar页用navigateBack/navigateTo跳转不生效

原因： tabBar页面必须用switchTab

修法： tabBar页面之间用switchTab，二级页面用navigateTo

教训： 跳之前先想清楚目标页是不是tabBar页

5. 星星被header遮挡

现象： 星空页前几颗星点了没反应

原因： 半透明header的层级比星星高，遮住了

修法： 调整层级或星星布局偏移

教训： 层级要统一规划，不要层层递加

6. 触摸事件坐标获取不全

现象： 点击星星位置偏移

原因： 只取了一种坐标来源

修法： 做兼容处理，多种坐标来源做fallback

教训： 触摸坐标来源不统一，必须做兼容

7. button默认样式导致文字不居中

现象： 按钮文字偏上或偏左

原因： 小程序button有默认padding、最小高度等属性

修法： 显式重置padding/margin，用flex居中

教训： 小程序组件的默认样式比HTML标签多，用之前先重置

8. 插件未授权导致小程序崩溃

现象： 加了朗读功能后整个小程序启动失败

原因： 声明了插件但没去公众平台后台授权

修法： 先授权插件，或用try-catch包裹插件调用

教训： 任何第三方插件都要先授权再声明

9. switchTab与navigateTo混用

现象： 有时能跳有时不能跳

原因： 搞混了哪些页是tabBar页哪些不是

修法： 明确区分tabBar页和非tabBar页，走不同的跳转方式

教训： 小程序的跳转体系比Web严格，不能混用

10. 学期切换后页面数据不刷新

现象： 切了学期，星空页还显示老数据

原因： 没有检测状态变化

修法： 检测学期信息，变了就重新加载

教训： 跨页面的状态变化要有监听机制

二、Web→小程序迁移坑（8个）

11. 3D星空跑不动

现象： Web上炫酷的3D星空，到小程序里白屏5-10秒，低端机卡爆

原因： 小程序WebGL支持有限，库文件体积大，性能差

修法： 降到2D Canvas手绘星空，不炫酷但流畅

教训： 小程序是"简单直接"的环境，炫技要向可用性妥协

12. 全局样式重置不生效

现象： 写的全局样式重置没有效果

原因： 小程序不支持Web的通用选择器写法

修法： 改用具体的选择器逐一写

教训： 小程序样式规则和Web不是一套，写之前先查官方支持列表

13. 没有浏览器对象可用

现象： 操作页面元素的方法直接报错

原因： 小程序是双线程架构，逻辑层没有浏览器功能

修法： 全部改成改数据→自动更新界面，用小程序自带的方法获取信息

教训： 从Web迁移，凡是操作页面元素的代码全部要重写

14. 本地存储不能用

现象： 本地存储报未定义

原因： 小程序没有浏览器那套本地存储

修法： 换成小程序的存储方式

教训： 小程序存储方式不同，迁移时要全局替换

15. 尺寸单位要换

现象： 不同屏幕尺寸上布局比例不对

原因： Web的尺寸单位在小程序上显示效果不同

修法： 按小程序推荐的比例换算

教训： 响应式布局在Web和用不同的单位体系

16. 页面跳转体系完全不同

现象： Web里随便跳，小程序里各种跳不动

原因： 小程序的跳转有严格规定

修法： 区分tabBar页和非tabBar页，用对应的跳转方式

教训： 小程序的导航体系比Web严格得多

17. 音频播放方式差异

现象： Web里直接就能播音频，小程序里播不了

原因： 小程序必须用特定的方式创建实例

修法： 用小程序的音频播放方式，离开页面时手动销毁

教训： 小程序里创建的实例都要手动销毁，不然会出问题

18. Canvas触摸坐标体系不同

现象： 点击canvas后位置偏移

原因： 小程序触摸坐标来源多样且不同

修法： 写兼容代码，在多个坐标来源之间做fallback

教训： 小程序canvas坐标要处理多个来源

三、人与AI协作坑（5个）

19. AI修一个问题引入两个新问题

现象： 修了拼音布局，撑开了整个页面；删了按钮，引用还在

原因： AI是点对点改代码，全局影响评估不全

修法： 每次改完让AI跑全量检查，不只改你说的地方

教训： 用AI改代码，你必须是审核的人，不是监工

20. AI把删掉的东西又加回来了

现象： 齿轮按钮删了两次，后续修改又被恢复

原因： 大模型有历史对话记忆，它可能推断你还需要

修法： 删除时一次性清掉所有相关文件代码，再搜索确认无残留

教训： 删除操作要明确告诉AI，后续修改不要恢复

21. AI加功能时不考虑前提条件

现象： 声明了插件但没授权，整个小程序崩溃

原因： AI只管"要实现X需要什么"，不管前提条件

修法： 让AI加第三方服务时，每次问一句"如果这个服务不可用会怎样"

教训： 防御性代码AI不会主动写，你得提醒它

22. AI会重复犯同样的错误

现象： 同一个问题在不同页面反复出现

原因： AI没有从上一个bug学习的能力

修法： 修完让AI全局搜索相似模式，一次性全改

教训： 修bug时让AI顺便在整个代码库里排查同一类问题

23. 需求沟通要具体

现象： 说"加个设置入口"，AI加了个按钮，但你要的是菜单选项

原因： 自然语言的模糊性，"入口"可以是一百种东西

修法： 说需求时多给一个参考例子，或明确"不是X是Y"

教训： 对AI说话越具体，它做出来的越接近你想要的

以上23个坑，三类别，标注了每个坑的"现象→原因→修法→教训"，可直接作为避坑参考。