Neo-ZQYY/_DEL/miniprogram-dev/05-lessons/pitfalls.md

踩坑速查与迁移经验

经 User 确认后录入的实践经验。AI 发现新踩坑点时先提出建议，User 确认后再录入。 按类别组织，每条记录包含：场景、问题、解决方案、影响页面。

---

WXML 模板

禁止在 {{}} 中调用 JS 方法

• 场景：WXML 模板中使用 .toFixed()、.map() 等
• 问题：小程序模板不支持 JS 方法调用
• 方案：用 WXS 模块 utils/format.wxs
• 影响：所有页面

TabBar 页面跳转必须用 wx.switchTab

• 场景：从非 tabBar 页面跳转到 task-list、board-finance、my-profile
• 问题：navigateTo 会静默失败
• 方案：tabBar 页面一律用 wx.switchTab
• 影响：所有涉及 tabBar 跳转的页面

---

样式与布局

一屏页面用 height: 100vh 而非 min-height

• 场景：login、reviewing、no-permission 等单屏页面
• 问题：min-height: 100vh 在某些情况下不生效
• 方案：height: 100vh + box-sizing: border-box
• 影响：login, reviewing, no-permission

状态栏适配禁止用 env(safe-area-inset-top)

• 场景：自定义 navBar 页面的顶部 padding
• 问题：小程序不支持 env() CSS 函数
• 方案：JS wx.getSystemInfoSync().statusBarHeight 动态设置
• 影响：所有自定义 navBar 页面

padding-top + 100vh 必须配合 box-sizing: border-box

• 场景：有顶部 padding 的全屏页面
• 问题：不加 box-sizing 会导致底部内容溢出
• 方案：始终添加 box-sizing: border-box
• 影响：所有全屏页面

---

TDesign 组件

t-button icon 只支持内置图标

• 场景：按钮中使用品牌图标（微信 logo 等）
• 问题：icon 属性只接受 TDesign 内置图标名
• 方案：用 <view> + <image> 组合替代
• 影响：login 页面微信登录按钮

TDesign 默认样式优先级高

• 场景：需要大幅覆盖 TDesign 组件样式
• 问题：CSS 变量和外部样式类不够用时，!important 也可能不生效
• 方案：直接用原生 <view> 实现，绕开样式干扰
• 影响：视具体组件

---

资源引用

所有 H5 内联 SVG 必须导出为独立文件

• 场景：H5 中直接写在 HTML 内的 <svg> 元素
• 问题：小程序不支持内联 SVG
• 方案：导出为 .svg 文件存放 assets/icons/，用 <image> 引用
• 影响：所有含内联 SVG 的页面

引用不存在的图片会 500 错误

• 场景：WXML 中 <image src> 指向不存在的文件
• 问题：不是 404 而是 500 错误，难以排查
• 方案：用 CSS 渐变、emoji、<t-icon> 替代；或确保文件存在
• 影响：所有页面

---

截图与对比

rpx 取整导致累积高度偏移

• 场景：多屏长页面的中间屏截图对比
• 问题：MP 页面总高度比 H5 短 ~10%，中间屏内容窗口错位
• 方案：使用锚点对齐法（按元素位置对齐而非 scrollTop 数值）
• 影响：board-finance, performance 等长页面
• 发现日期：2026-03-10

AI 浮动按钮动画造成随机差异

• 场景：截图时 ai-float-button 的 gradientShift 动画处于不同帧
• 问题：每次截图差异 ~1%
• 方案：双端截图前隐藏（H5 用 JS，MP 用 wx:if="{{false}}")
• 影响：所有含 ai-float-button 的页面
• 发现日期：2026-03-10

禁止跨维度套用布局假设，H5 原型是唯一视觉真相

• 场景：board-customer "最专一"卡片的 .loyal-table 布局
• 问题：其他维度（最应召回等）的 card-mid-row / card-assistant-row 有 ml-11（80rpx 对齐头像右侧），开发时"合理推断"表格也应该加 margin-left: 80rpx。但 H5 原型中表格容器没有 ml-11，是从卡片 padding 开始的（left=16px）。Playwright 实测才发现偏差
• 方案：每个维度的每个组件都必须回到 H5 HTML 逐一确认 Tailwind 类，禁止从其他维度"类推"。不确定时用 Playwright getBoundingClientRect() 实测 H5 元素位置
• 影响：所有多维度页面（board-customer 8 维度、board-coach 4 维度）
• 发现日期：2026-03-12

H5 与 MP mock 数据不同，像素级 diff 需结合结构比对

• 场景：用 PIL/numpy 或 image-compare 对比 H5 和 MP 截图
• 问题：H5 原型使用硬编码 mock 数据（如孙先生/王先生/李女士），MP 使用后端返回的测试数据（王先生/李女士/张先生），文字内容不同导致像素 diff 高达 11%，18 个分段覆盖全页面，无法区分"数据差异"和"样式差异"
• 方案：像素级 diff 仅用于发现大面积结构偏移（窗口错位、整块缺失）。样式还原度验证的主要方法是 Tailwind 类→rpx 值逐项比对表，逐一确认每个 CSS 属性的换算结果
• 影响：所有页面的截图对比流程
• 发现日期：2026-03-12

Tailwind→WXSS 映射必须逐项建表验证

• 场景：将 H5 Tailwind 类翻译为小程序 WXSS
• 问题：凭记忆或经验直接写 WXSS 值容易出错——font-medium 是 500 不是 600，gap-1 是 4px 不是 2px，space-y-2 是 8px 不是 4px。错误在视觉上不明显但会累积
• 方案：对每个组件建立完整的对照表（H5 Tailwind 类 → 计算值 px → rpx 换算 → MP WXSS 值），逐行核对。参考速查表：2→4, 4→8, 6→10, 8→14, 10→18, 12→22, 14→24, 16→28, 20→36, 24→42
• 影响：所有页面的 WXSS 编写
• 发现日期：2026-03-12

相邻元素间距叠加导致高度翻倍

• 场景：经营一览的 .overview-grid-2 底部 padding 32rpx + .ai-insight-section margin-top 32rpx，间距翻倍为 64rpx
• 问题：H5 中 grid 无 margin-bottom，间距完全由下方元素的 mt-4(16px) 提供。MP 中两端都加了间距，导致块间距翻倍、整体高度偏高
• 方案：校对间距时必须确认「这段间距是谁提供的」——上方元素的 padding-bottom 还是下方元素的 margin-top。用 Playwright getComputedStyle 实测 H5 两个相邻元素的 margin/padding，确认间距归属后只在一端设置
• 影响：所有包含多个子区块的板块（经营一览、预收资产等）
• 发现日期：2026-03-12

用 Playwright 实测 H5 比手动解析 Tailwind 更可靠

• 场景：H5 原型文件是单行 minified HTML，手动读取 Tailwind 类名容易遗漏或误判
• 问题：Tailwind 类名组合后的实际渲染值不直观（如 p-4 在嵌套容器中可能被覆盖，space-y-2 的实际 gap 取决于子元素数量），手动推算容易出错
• 方案：通过 browser_run_code 创建 375×812 viewport + DPR 1.5 的 context，用 getComputedStyle + getBoundingClientRect 直接拿到渲染后的实际 px 值，再按换算规则转 rpx。这个方法应作为所有页面校对的标准流程
• 影响：所有页面的 WXSS 校对流程
• 发现日期：2026-03-12

Tailwind 字号类自带 line-height，WXSS 必须同步补齐

• 场景：校对经营一览的现金流水概览 4 个块，H5 明显比 MP 高

• 问题：Tailwind 的 text-xs/text-sm/text-lg/text-xl 等字号类捆绑了特定的 line-height（如 text-lg = font-size: 18px; line-height: 28px），但 WXSS 只写了 font-size 没写 line-height，小程序默认行高约 1.2，远小于 Tailwind 的行高，导致每行文字占据的垂直空间不足，块整体矮了一截

• 方案：每个 Tailwind 字号类转 WXSS 时，必须同时写 font-size 和 line-height。完整对照表（87.5% 缩放）：

  Tailwind	font-size (px)	line-height (px)	WXSS font-size	WXSS line-height
  text-xs	12	16	22rpx	28rpx
  text-sm	14	20	24rpx	34rpx
  text-base	16	24	28rpx	42rpx
  text-lg	18	28	32rpx	48rpx
  text-xl	20	28	36rpx	48rpx
  text-2xl	24	32	42rpx	56rpx

• 影响：所有页面的所有文字元素

• 发现日期：2026-03-12

---

新增经验请按以上格式录入，包含：场景、问题、解决方案、影响页面、发现日期（可选）。