很多新手第一次做 uni-app 项目最容易被“我点了一遍没报错”骗到。首页能打开。列表能显示。发布按钮点了也有反应。然后你就以为项目好了。但真实用户不会只走你刚才点过的那条路。用户会断网会快速点两次会输入奇怪价格会从详情页返回会在微信小程序里打开会在安卓低端机里上传图片。质量保证不是为了显得专业。是为了提前遇到这些麻烦。太长不看版这一篇你先记住一条排查顺序。复现步骤。控制台错误。网络请求。接口响应字段。页面状态。平台差异。不要一出问题就猜也不要一上来就改代码。调试的本质是找出“现实数据”和“代码预期”在哪一刻分开了。这一篇放在系列里的位置如果你还没有列表页的 loading、empty、error、success 状态先看 08-网络请求与页面状态设计.md。如果你还不熟悉条件渲染和列表渲染先看 05-条件渲染与列表渲染.md。如果你要发布前做检查后面接着看 16-部署发布策略.md。这一篇解决的是你写出来以后怎么判断它不是“碰巧能跑”。先从一个具体故障开始商品列表没数据假设你写了一个商品列表页。页面打开后没有报错但就是没有商品。很多人第一反应是改v-for。但问题可能不在模板。可能是接口没请求。可能是请求地址错了。可能是后端返回字段叫records你代码里读的是list。可能是状态一直停在loading。也可能是你筛选参数传错了后端正常返回空数组。调试要按路径来。商品列表没数据确认复现步骤看控制台是否报错看 Network 请求是否发出看状态码和响应体核对字段名和数据结构看页面状态是否正确切换修复后补最小用例这张图很重要。它能帮你少走很多冤枉路。第一步先写清楚复现步骤“列表不显示”不是一个合格的问题描述。合格的问题描述至少包括四件事。项目示例运行平台H5 / 微信小程序 / App 真机入口路径首页点击“全部商品”进入列表页操作步骤选择分类“数码”点击搜索实际结果页面显示空态预期结果应显示 8 条商品你可以在项目里建一个简单的问题记录模板。// 文件位置docs/debug-template.md# 问题记录 - 平台 - 入口页面 - 复现步骤 - 实际结果 - 预期结果 - 控制台错误 - 请求地址 - 响应状态码 - 响应体关键字段 - 初步判断这个模板看起来很朴素但它能逼你把问题从“感觉坏了”变成“哪一步坏了”。第二步看控制台但别只看控制台控制台能发现语法错误、变量不存在、Promise 未捕获异常等问题。比如你写了下面这段。// 文件位置pages/goods/list.vueconstloadGoodsasync(){constresawaitrequest({url:/goods})goodsList.valueres.list}如果res是undefined控制台可能会报错。但如果res存在只是res.list是undefined模板里的v-for可能只是渲染不出来不一定有明显错误。所以控制台只能告诉你一部分真相。接下来必须看网络请求。第三步看 Network不要只盯着页面商品列表没有数据时打开浏览器 DevTools 或微信开发者工具的 Network 面板重点看这些。检查点你要确认什么请求是否发出页面进入时有没有请求/goodsURL 是否正确baseURL、路径、查询参数是否拼对method 是否正确GET / POST 有没有写错statusCode200、401、403、500 分别代表不同问题response返回字段是否和代码预期一致请求次数是否重复请求、快速切换时是否乱序假设接口返回是这样。{code:0,data:{records:[{id:1,title:二手键盘,price:99}],total:1}}但你的页面写的是这样。// 文件位置pages/goods/list.vueconstloadGoodsasync(){constresawaitrequest({url:/goods})goodsList.valueres.list||[]}那当然没有数据。不是v-for坏了。是字段路径错了。应该改成这样。// 文件位置pages/goods/list.vueconstloadGoodsasync(){constresawaitrequest({url:/goods})goodsList.valueres.data?.records||[]}更稳一点可以在请求层统一拆包避免每个页面都猜接口结构。这个思路在 08-网络请求与页面状态设计.md 里已经讲过。第四步看页面状态有没有走错列表页通常有四种状态。有数据空数组请求失败点击重试修改筛选下拉刷新loadingsuccessemptyerror页面没有数据不一定是 bug。如果接口确实返回空数组就应该显示空态。如果接口失败就应该显示错误态。如果一直显示 loading就是状态没有在finally里收口。// 文件位置pages/goods/list.vueconststatusref(idle)constgoodsListref([])constloadGoodsasync(){status.valueloadingtry{constresawaitrequest({url:/goods})goodsList.valueres.data?.records||[]status.valuegoodsList.value.length?success:empty}catch(error){status.valueerror}}这里不要偷懒。很多线上问题不是接口完全坏了而是页面状态没设计好。用户看到一个永远转圈的 loading比看到“加载失败点击重试”更崩溃。第五步真机调试不能省H5 能跑不代表微信小程序能跑。微信开发者工具能跑不代表真机能跑。真机尤其要测这些能力。图片选择和上传。扫码。定位。分享。支付。文件预览。安全区域适配。慢网和断网。如果你的商品应用有发布页至少拿一台安卓机和一台 iPhone 测一次图片上传。因为图片临时路径、文件大小、压缩结果、权限提示在不同平台上都可能有差异。前面 11-小程序特性与多端适配.md 讲的条件编译和平台差异在这里会变成真实问题。不要只测成功路径测试时最常见的偷懒是只测“正常用户正常操作”。商品应用至少要测这些。商品应用测试页面状态loadingemptyerrorsuccess表单输入标题为空价格为0价格非数字图片未上传用户操作快速重复点击返回重进下拉刷新切换分类网络环境断网慢网401登录失效500服务异常平台设备H5微信小程序Android真机iPhone真机这不是让你一开始就搭一套完整自动化测试体系。零基础阶段先把关键路径手动测明白就已经比“随便点点”靠谱很多。从纯函数开始写可测试代码很多人一听测试就觉得很重。其实可以从最简单的纯函数开始。比如商品价格格式化。// 文件位置utils/format.jsexportconstformatPrice(price){constvalueNumber(price)if(Number.isNaN(value)||value0){return0.00}return${value.toFixed(2)}}这个函数非常适合测试因为输入输出明确没有页面、网络、缓存这些副作用。你哪怕暂时不用测试框架也可以先列出用例。输入预期输出1212.009.99.90abc0.00-10.00当页面逻辑越来越复杂时把格式化、参数拼接、状态判断抽成纯函数后面会轻松很多。给关键流程留调试开关开发阶段可以打印日志但别乱打。更好的方式是封装一个开发日志方法。// 文件位置utils/logger.jsconstisDevprocess.env.NODE_ENVdevelopmentexportconstdevLog(...args){if(!isDev){return}console.log(...args)}页面里这样用。// 文件位置pages/goods/list.vuedevLog(商品列表响应,{total:res.data?.total,count:res.data?.records?.length})注意只打印调试需要的字段不要打印完整 token、手机号、地址。日志脱敏可以回看 14-安全防护与数据保护.md。发布前的最小质量清单模块至少检查首页首屏加载、图片显示、分类入口、空数据兜底商品列表loading、empty、error、分页、筛选、下拉刷新商品详情参数缺失、商品不存在、图片加载失败发布页表单校验、重复提交、图片上传失败、登录失效登录态token 过期、退出登录、重新进入页面网络慢网、断网、接口 500、接口字段变化平台H5、小程序、至少一台真机这张表可以贴到你的项目 README 或上线检查文档里。真正开始做项目后你会发现它救命。这里容易翻车只看页面不看 Network字段名错了还在改模板。只测成功路径没有测空态、错误态、断网、重复点击。状态只写loading请求失败后没有 error 页面。开发工具里正常就不做真机测试。控制台打印完整用户信息上线后忘了删。接口返回结构变了页面没有兜底直接白屏。表单提交没有按钮锁用户连点两次发出两个请求。修完 bug 没记录复现步骤下次同类问题又从头猜。自己试试故意把商品列表接口字段从records改成items看看页面会出现什么状态再补一个兜底提示。给发布按钮加一个submitting状态提交中禁止重复点击。在列表页模拟接口失败确认页面能显示错误态并且点击重试能重新请求。用真机测试一次图片选择和上传记录 H5、小程序、App 的差异。这一篇先记住什么调试不是猜。测试也不是点一下页面。先复现再看控制台再看网络再核对响应字段再检查页面状态最后再改代码。质量保证的目标不是把项目变复杂。是让你知道每个关键流程在正常、异常、慢网、断网、跨平台时会发生什么。一个能解释问题、能复现问题、能验证修复的人才算真正开始会做项目。