学微信小程序开发，一上来就被各种框架和文档砸晕。其实，小程序开发的核心逻辑并不复杂——它本质上是一个“页面+逻辑”的轻量级应用。今天这篇文章，我会用一种更贴近实战的方式，带你一步步从零搭建一个完整的小程序页面，过程中会穿插一些容易踩坑的细节、对比不同写法的优劣，以及一些官方文档里不会明说的“潜规则”。

一、环境搭建：别急着写代码，先搞定“地基”

打开微信开发者工具，你可能会看到“新建项目”按钮。这里有个关键点：项目名称不要用中文，否则后续在真机调试时，某些安卓机型会出现路径识别错误。AppID选择“测试号”就行，等正式上线时再替换为真实AppID。

创建完成后，你会看到左侧的目录结构。很多新手会困惑：为什么有四个文件夹？其实只需要关注两个核心：pages（页面）和 app.json（全局配置）。举个例子，如果你要做一个“商品列表”页面，直接在 pages 下新建一个 goods 文件夹，里面放四个同名文件（.wxml、.wxss、.js、.json）。这里有个小技巧：用开发者工具的“新建页面”功能，比手动创建文件更安全，因为它会自动在 app.json 里注册路径，省去你手动配置的麻烦。

二、页面结构：WXML 不是 HTML，别混为一谈

打开 goods.wxml，你会发现它长得像 HTML，但标签完全不同。比如 <view> 替代了 <div>，<text> 替代了 <span>。这里有个容易犯的错误：在 <text> 标签里嵌套 <view>，这在真机上会导致文字显示异常。记住一个原则：<text> 只能包含纯文本或 <text> 本身。

看一个实际案例：假设你要展示一个商品卡片，包含图片、标题和价格。用 <view> 做容器，里面放 <image>（图片）、<text>（标题）、<text>（价格）。注意 <image> 必须指定 mode 属性，否则图片会变形。比如 mode="aspectFill" 可以保持比例裁剪，适合商品图。

三、数据绑定：{{ }} 双花括号的“坑”与“解”

在 goods.js 的 data 对象里定义变量：goodsName: '夏季T恤'。然后在 WXML 里用 {{ goodsName }} 渲染。但这里有个没注意到的细节：数据绑定不能直接写表达式。比如 {{ price + 10 }} 在旧版本基础库会失效。正确做法是在 JS 里先计算好，再赋值给 data。

对比两种写法：

错误示例：<text>{{ price * 0.8 }}</text>（某些机型显示 NaN）

正确示例：在 onLoad 里执行 this.setData({ discountPrice: this.data.price * 0.8 })，再绑定 {{ discountPrice }}。

这个习惯能帮你避免很多莫名其妙的 bug，尤其是在处理用户输入或异步数据时。

四、事件绑定：bindtap 和 catchtap 的区别，90% 的人用错

给按钮添加点击事件，通常用 bindtap="handleClick"。但如果你在父元素和子元素上同时绑定了 tap 事件，bindtap 会触发冒泡，导致两个事件都执行。这时用 catchtap 可以阻止冒泡。举个例子：

你有一个商品列表，点击整个卡片跳转详情页，但点击卡片里的“收藏”按钮只触发收藏。如果都用 bindtap，点击收藏按钮会同时触发跳转。解决方案：在收藏按钮上用 catchtap，这样事件就不会传到父级。

另外，传递参数时不要直接在事件名后加括号，比如 bindtap="handleClick(123)" 是无效的。正确做法是用 data-* 自定义属性：<view data-id="123" bindtap="handleClick">，然后在 JS 里通过 event.currentTarget.dataset.id 获取。

五、条件渲染：wx:if 和 hidden，选错会卡死页面

当需要控制元素显示隐藏时，wx:if 和 hidden 都能实现，但机制完全不同。wx:if 是“真·条件渲染”，元素会被销毁或重建，适合切换频率低的场景；hidden 只是用 CSS 控制显示（display:none），元素始终存在，适合频繁切换。

举例：一个“加载中”的转圈图标，如果数据加载很快（比如 1 秒内完成），用 wx:if 会导致每次切换都重新创建节点，浪费性能。这时候用 hidden 更合适。反之，一个很少出现的“错误提示”弹窗，用 wx:if 可以节省内存。

这里有个扩展技巧：结合 wx:elif 和 wx:else 实现多状态切换。比如根据 status 值显示“加载中”“空数据”“错误页”三种状态，比用 hidden 写多个判断更清晰。

六、列表渲染：wx:for 的 key 值，不写会报警告

循环渲染商品列表：<view wx:for="{{ goodsList }}" wx:for-item="item" wx:key="id">。这里 wx:key 必须写，否则控制台会报黄色警告。key 的作用是提高渲染性能，尤其是列表数据变化时（比如删除或排序）。如果数据没有唯一 id，可以用 wx:key="*this"，但只适用于纯文本数组。

另外，wx:for-item 可以自定义循环变量名，默认是 item。如果你嵌套循环，一定要改名字，比如外层用 item，内层用 subItem，否则会互相覆盖。

七、样式编写：rpx 是神器，但别滥用

小程序里用 rpx 做自适应单位，1rpx 等于屏幕宽度的 1/750。但有些场景不适合：比如边框宽度，用 1rpx 在某些高清屏上会显示模糊，建议直接用 1px。还有字体大小，用 rpx 会导致在不同屏幕上的字号差异过大，建议正文用 28rpx 左右，标题用 32rpx 到 36rpx。

对比一下：用 px 固定尺寸，在 iPhone 5 上会显得很大，在 iPhone 12 Pro Max 上又很小。而 rpx 能自动缩放，但也要注意极限情况——在折叠屏或平板设备上，rpx 计算出的值可能过大，导致布局溢出。这时候可以用 max-width 做限制。

八、生命周期：onLoad 和 onShow 的区别，决定你的数据刷新时机

习惯把所有逻辑都放在 onLoad 里，但如果你从另一个页面返回（比如从详情页返回列表页），onLoad 不会再次执行，导致数据还是旧的。这时候需要用 onShow。举个例子：

一个购物车页面，用户从购物车点击商品进入详情页，修改数量后返回。如果只在 onLoad 里请求数据，返回时页面不会刷新。正确做法：把请求数据的函数放在 onShow 里，或者同时在 onLoad 和 onShow 里调用，但用缓存判断是否真的需要重新请求。

另外，onReady 在页面首次渲染完成时触发，适合做动画或第三方插件的初始化。但注意：onReady 只在页面加载时执行一次，和 onLoad 类似，区别在于 onLoad 可以接收跳转参数。

九、网络请求：wx.request 的“潜规则”

调用接口时，wx.request 的 url 必须是小程序后台配置的合法域名，否则在真机上会报错。开发时可以勾选“不校验合法域名”选项，但上线前一定要配好。这里有个坑：如果接口需要携带 Cookie，小程序默认不会自动保存，需要手动处理 set-cookie 头，或者用 token 验证。

另外，wx.request 的 success 回调里，res.data 才是真正的返回数据，res 本身包含 statusCode、header 等信息。直接拿 res 当数据用，导致渲染失败。写个判断：if (res.statusCode === 200) { this.setData({ list: res.data }) }。

对于并发请求，可以用 Promise.all 或者 wx.request 的 complete 回调做聚合。但注意：小程序同时发起的请求数有限制（通常是 10 个），超过的会排队等待，影响用户体验。

十、本地存储：setStorageSync 和 getStorageSync 的同步陷阱

用 wx.setStorageSync 存数据，wx.getStorageSync 取数据。但同步操作会阻塞线程，如果存储的数据量很大（比如几千条商品信息），页面会卡顿。这时候用异步版本 wx.setStorage 更安全。

举例：用户登录后，把 token 存到本地。如果用同步操作，在 onLoad 里调用，会导致页面渲染延迟。换成异步：wx.setStorage({ key: 'token', data: token })，然后在回调里做后续处理。

另外，wx.getStorageSync 如果 key 不存在，会返回 undefined，而不是 null。写判断时注意：if (token !== undefined) 而不是 if (token)，因为空字符串也是假值，但可能是有意义的业务数据。

十一、组件化：自定义组件，让你的代码“瘦”下来

当页面越来越复杂，把所有代码写在一个文件里会变得难以维护。这时候可以拆分成自定义组件。比如一个