小程序开发避坑指南：9年实战总结的10条铁律
分类：前端 | 标签：微信小程序、小程序开发、性能优化
我9年前端开发经历中，做过的小程序项目不下20个——电商、社区团购、点餐、工具类……大大小小都踩过坑。
今天总结10条最关键的小程序开发铁律，都是血泪教训。
铁律1：setData不要传大数据
setData是小程序最大的性能瓶颈——它是跨线程通信（逻辑层→渲染层），数据量越大越卡。
// ❌ 致命操作
this.setData({ list: 500条商品数据 })
// ✅ 路径更新，只传变化的
this.setData({ 'list[3].status': 'sold' })
// ✅ 列表用分页加载
loadMore() {
const newItems = await fetchPage(this.page++)
const start = this.data.list.length
const patch = {}
newItems.forEach((item, i) => {
patch[`list[${start + i}]`] = item
})
this.setData(patch)
}
铁律：单次setData数据量控制在256KB以内，能路径更新的绝不整体更新。
铁律2：分包必须做，主包控制在2MB以内
小程序主包大小限制2MB，超了直接上传失败。但很多人在主包快满的时候才想起分包，这时候改成本极高。
{
"pages": ["pages/index/index", "pages/mine/mine"],
"subpackages": [
{
"root": "packageShop",
"pages": ["pages/list/list", "pages/detail/detail"]
},
{
"root": "packageUser",
"pages": ["pages/order/order", "pages/address/address"]
}
],
"preloadRule": {
"pages/index/index": {
"network": "all",
"packages": ["packageShop"]
}
}
}
铁律：项目一开始就规划分包，主包只放首页和tabBar页面，业务模块全部分包。配合preloadRule预加载。
铁律3：页面栈最多10层
wx.navigateTo连续调用超过10次，第11次静默失败——页面打不开，也不报错。
// ✅ 封装一个安全的导航函数
function safNavigate(url) {
const pages = getCurrentPages()
if (pages.length >= 9) {
wx.redirectTo({ url }) // 替换当前页
} else {
wx.navigateTo({ url }) // 新开页面
}
}
铁律：列表→详情→详情这种链式跳转场景，超过5层就用redirectTo。
铁律4：图片用CDN+压缩，本地图片只放icon
把大图放在小程序包内是新手最常犯的错——浪费包体积，加载还慢。
<!– ❌ 本地大图 –>
<image src="/images/banner.png" />
<!– ✅ CDN图片 + 懒加载 –>
<image
src="https://cdn.xxx.com/banner.jpg?x-oss-process=image/resize,w_750/format,webp"
lazy-load
mode="widthFix"
/>
铁律：除了小icon（<10KB），所有图片走CDN。用OSS/COS的图片处理参数自动裁剪压缩。
铁律5：接口请求封装统一错误处理
// ✅ 封装request
function request(options) {
return new Promise((resolve, reject) => {
const token = wx.getStorageSync('token')
wx.request({
url: BASE_URL + options.url,
method: options.method || 'GET',
data: options.data,
header: {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/json',
},
success(res) {
if (res.statusCode === 401) {
wx.removeStorageSync('token')
wx.reLaunch({ url: '/pages/login/login' })
return reject(new Error('登录过期'))
}
if (res.statusCode !== 200 || res.data.code !== 0) {
wx.showToast({ title: res.data.msg || '请求失败', icon: 'none' })
return reject(res.data)
}
resolve(res.data.data)
},
fail(err) {
wx.showToast({ title: '网络异常', icon: 'none' })
reject(err)
},
})
})
}
铁律：所有接口必须经过统一封装，token过期自动跳登录，错误统一提示，不要每个页面各写各的。
铁律6：Storage操作必须try-catch
// ❌ 裸调用——Storage满了直接crash
wx.setStorageSync('data', hugeData)
// ✅ 容错处理
function safeSetStorage(key, data) {
try {
wx.setStorageSync(key, data)
} catch (e) {
console.error('Storage写入失败', e)
// 清理过期缓存后重试
cleanExpiredCache()
try { wx.setStorageSync(key, data) } catch (_) {}
}
}
铁律：小程序Storage上限10MB，写入操作必须try-catch，做好容错和清理机制。
铁律7：用户授权流程要做兜底
微信更新后，getUserProfile、getPhoneNumber等授权API经常变。不要依赖授权成功，必须做兜底。
// ✅ 授权失败也能用
async function getUserInfo() {
try {
const res = await wx.getUserProfile({ desc: '用于展示' })
return res.userInfo
} catch (e) {
// 用户拒绝授权，使用默认信息
return { nickName: '微信用户', avatarUrl: '/images/default-avatar.png' }
}
}
铁律：任何授权相关操作都假设用户可能拒绝，做好默认值兜底。
铁律8：自定义组件用Component构造器
// ❌ 在Page里写复杂逻辑
Page({
data: { /* 几十个字段 */ },
methods: { /* 几十个方法 */ },
})
// ✅ 抽成自定义组件
Component({
properties: {
item: { type: Object, value: {} }
},
data: { expanded: false },
methods: {
toggle() { this.setData({ expanded: !this.data.expanded }) }
}
})
铁律：页面超过300行就该拆组件。Component构造器比Page更强大（支持observers、lifetimes、behaviors）。
铁律9：小程序码参数有32字符限制
// ❌ 直接拼长参数
scene = "id=123456&type=share&from=poster&ref=abc" // 超过32字符！
// ✅ 用短码映射
// 后端生成短码，前端扫码后请求后端解析
scene = "s_abc123" // 短码，不超过32字符
// 前端解析
onLoad(options) {
if (options.scene) {
const scene = decodeURIComponent(options.scene)
const params = await api.decodeScene(scene)
}
}
铁律：小程序码的scene参数最多32个可见字符。复杂参数通过后端映射处理。
铁律10：上线前跑一遍体验评分
微信开发者工具内置了「体验评分」功能，上线前必跑。它会检查：
- setData数据量是否过大
- 图片是否过大
- 是否有未绑定key的列表
- HTTPS域名是否配置
- 是否有废弃API使用
铁律：上线前体验评分必须≥80分。低于这个分数，用户体验一定有问题。
总结
做小程序，技术不难，坑多。上面10条铁律是20+个项目踩出来的。收藏好，每次新项目开始前对照检查一遍。
你在小程序开发中踩过什么坑？评论区聊聊。
我是前端老兵AI，9年+前端工程师，做过20+个小程序项目
