说实话菜谱类小程序看起来简单真做起来才知道坑有多密。“探菜秘谱”这个项目我从零开始搭表面上是几个列表页加一个详情页实际动手后发现它几乎把小程序的常用能力全部覆盖了一遍自定义导航栏、分类检索、列表分页、图片懒加载、收藏互动、分享卡片、canvas 海报甚至还有版本发布和审核。整套系统做完等于把 UniApp 开发微信小程序的完整路径走了一遍。这套系统的定位是一个面向普通家庭的菜谱库用户可以浏览每日推荐、按分类找菜、搜索菜名和食材、查看图文步骤、收藏喜欢的内容也可以自己上传菜谱。项目采用 UniApp 框架开发可编译到微信小程序平台前端页面和后端接口联动数据层用 MySQL 或 UniCloud 云数据库都行。如果你正在做一个与“菜谱/美食/内容展示”相关的课程设计、毕业设计或者想用 UniApp 做一款内容型小程序那这篇复盘应该能帮你少走不少弯路。1. 菜谱类小程序的需求剖析用户找菜谱时真正在意什么1.1 三个核心痛点找菜难、做菜难、收藏吃灰别急着写代码先想清楚用户打开这个小程序是为了什么。我梳理下来用户的真实痛点集中在三个地方。第一个是“找菜难”。不知道自己想吃什么打开菜谱应用翻半天也决定不了。这时候用户需要的是推荐和分类——首页要有“今日推荐”“热门菜谱”这类内容推送分类页要按菜系、菜品类型、烹饪方式、适用场景等维度组织尽量降低用户的决策成本。很多菜谱应用只把菜谱做成了一个搜索工具忽略了“帮我做决定”这个场景这其实是首页信息流的核心价值。第二个是“做菜难”。用户找到菜谱后真正跟着做的时候需要看到的是清晰的信息结构食材清单、调料用量、准备时间、烹饪时间、分步说明、关键步骤配图。如果详情页只是铺一大段文字用户翻手机翻得怀疑人生。这里的关键是把步骤结构化让用户一步步跟着走每个步骤配上明确的说明和图片必要时支持“步骤倒计时”这类细节功能。第三个是“收藏吃灰”。很多人收藏了一堆菜谱但过后再也不打开。这个问题做产品设计时要前置思考不能只做一个收藏按钮。我最终的方案是在个人中心同时提供“我的收藏”和“最近浏览”并给收藏列表增加“做过”状态标记。用户做完一道菜可以打个勾这会让收藏列表有反馈感也会提高用户回访概率。这三个痛点分析清楚了功能清单自然就出来了。1.2 用户角色与核心用例从“今晚吃什么”到“端上桌”菜谱系统的用户角色可以划分为游客、注册用户和管理员三类。游客能浏览信息流、看分类页、看菜谱详情注册用户在前者基础上可以收藏、点赞、评论、上传菜谱管理员负责审核用户上传的菜谱维护分类和推荐位。举个例子一个厨房新手的完整操作路径是这样打开小程序进入首页——在“今日推荐”里翻到一道糖醋排骨——点开详情页看到食材清单和步骤——确认家里材料基本够——点击收藏——周末按步骤做了一次在收藏里勾掉“做过”。另一类用户是按需搜索想吃鱼直接搜“清蒸鲈鱼”再用“耗时小于30分钟”的条件筛一遍最后决定做哪一道。从这两个路径可以看出核心用例至少有这些浏览首页推荐内容与轮播图按分类浏览菜谱列表并分页加载关键词搜索菜谱并支持分类、难度、时长等组合筛选查看菜谱详情包含食材、调料、步骤、耗时、热量等字段收藏和取消收藏菜谱点赞、评论菜谱上传个人菜谱并提交审核管理后台对菜谱内容进行审核与管理1.3 内容与运营视角没有菜谱内容的功能只是空壳菜谱类小程序还有一个特殊之处功能是骨架内容才是血肉。项目启动阶段就要考虑数据从哪来。我的做法是“预置种子数据 用户上传 管理员审核”三层结构。种子数据至少要覆盖多种常见分类比如家常菜、川菜、粤菜、烘焙、汤粥、凉菜、主食、减脂餐等每个分类下准备一定数量的菜谱。每条菜谱内容需要包含完整的食材清单、调料用量、分步说明和至少一张封面图。图片使用线上 CDN 地址开发阶段可以直接用云存储的临时链接上线前再切到正式域名避免小程序图片域名白名单问题。如果你不想手动准备大量菜品数据可以先用爬虫思路整理一批公开菜谱数据但要注意版权和合规问题尽量使用自采数据或免费授权的数据源这也是很多毕设项目容易忽视的地方。数据真实度和完整度直接影响项目演示效果一个只有两三条数据的菜谱系统再好看也撑不住。2. 技术选型权衡为什么拿UniApp来做而不是原生小程序2.1 UniApp与原生小程序的取舍很多人问只做微信小程序为什么不直接用原生我当时的考虑是跨端冗余和开发效率。UniApp 的核心价值在于一套 Vue 代码可以编译到微信、支付宝、抖音、H5、App 等多端。虽然当前阶段主要目标是微信小程序但后续想上线抖音小程序或者做一个 H5 版做网页推广时原生小程序就会变得很尴尬而 UniApp 可以直接复用大部分代码。另外UniApp 的 Vue 开发体验比原生小程序的 WXML/WXSS 更接近传统前端开发组件化、数据绑定和生命周期管理都更顺手。但要注意这个优势是建立在 Vue 基础上的——如果你完全没接触过 Vue建议先花一周时间补一下基础否则写起来会感觉处处别扭。从项目维护角度讲UniApp 的工程结构也更清晰页面、组件、静态资源、配置文件的组织方式都比较规范对于需要写设计文档和答辩PPT的设计实现类项目来说这能省不少事。对比项UniApp原生微信小程序开发语言Vue 模板语法WXML / WXSS / JS跨端能力一套代码多端编译仅限微信组件生态uview-plus、uni-ui 等WeUI 及自定义学习曲线熟悉 Vue 即可上手需额外学习小程序语法调试方式HBuilderX 微信开发者工具微信开发者工具后期扩展可发 H5、App、多端小程序每端各写一套2.2 环境搭建里最容易疏忽的几个点UniApp 的官方 IDE 是 HBuilderX配合微信开发者工具一起用。环境配置上有几个细节很容易忽略踩到了会卡半天。第一个是 manifest.json 里必须正确配置微信小程序的 AppID。如果留空或者填了测试号上传、真机预览、部分插件功能都会报错。这个 AppID 要去微信公众平台注册小程序账号后获取。第二个是微信开发者工具里的“不校验合法域名”开关。开发阶段为了方便联调需要在开发者工具的“详情—本地设置”里勾选不校验合法域名。但上线前一定要关闭因为线上环境所有请求域名必须配置在白名单里不然接口全部请求失败。第三个是依赖问题。如果项目里用到了 npm 包需要在 HBuilderX 里开启“启用 uni-app 编译 Node.js 依赖”这个选项否则第三方库引入不生效。我自己第一次用 mp-html 组件时就是没开这个选项页面一直空白排查了半小时。2.3 UI组件库uview-plus还是uni-ui以及什么时候都不该盲选组件库方面我最终选了 uview-plus。注意这个选择有版本背景如果项目是 Vue2 版本可以选 uView如果是 Vue3要选 uview-plus因为原版 uView 已经停止维护直接硬搞会有一堆兼容问题。组件库能帮我们省下大量表单、弹窗、加载反馈类组件的开发时间。菜谱项目里用到的 rate 评分、tag 标签、swiper 轮播等组件uview-plus 都有现成的比自己手写更稳定。不过也别滥用项目里那些简单的视图展示组件比如列表项、卡片我都是自己写的这样页面控制更好包体也更小。安装 uview-plus 时要注意三件事main.js 里注册、uni.scss 里引入主题文件、pages.json 里配置 easycom 规则。配置完成后自定义组件才能自动导入不需要手动一个个注册。网上很多教程只讲前面两步忘记讲 easycom导致组件一直不渲染。3. 前端核心功能的落地实现3.1 自定义导航栏处理顶部高度、胶囊对齐和全面屏适配菜谱项目一开始我打算直接用微信小程序的默认导航栏但后来发现默认导航栏只能设置标题文字和背景色无法在导航栏区域内放搜索框或分类标签于是果断改成了自定义导航栏。自定义导航栏最核心的问题是怎么对齐胶囊按钮。微信小程序的胶囊按钮固定在右上角不同机型上它的位置会略有差异尤其是全面屏和非全面屏之间。我的实现方式是通过 uni.getSystemInfoSync 获取 statusBarHeight状态栏高度和系统信息再用 uni.getMenuButtonBoundingClientRect 拿到胶囊按钮的位置信息动态计算导航栏高度和布局。基本计算逻辑是导航栏总高度等于状态栏高度加胶囊按钮高度再加上下间距。导航栏内左侧放返回按钮和标题右侧尽量避开胶囊按钮区域。为了适配所有机型我封装了一个计算顶部安全区域的工具函数页面所有需要自定义导航的地方都统一调用。这样不用为每个页面单独写一套高度判断代码。const systemInfo uni.getSystemInfoSync() const menuButton uni.getMenuButtonBoundingClientRect ? uni.getMenuButtonBoundingClientRect() : null export function getNavBarInfo() { const statusBarHeight systemInfo.statusBarHeight || 0 let navBarHeight 44 if (menuButton) { navBarHeight (menuButton.top - statusBarHeight) * 2 menuButton.height } return { statusBarHeight, navBarHeight, totalHeight: statusBarHeight navBarHeight } }这里有个细节要注意uni.getMenuButtonBoundingClientRect 只有微信小程序平台支持在 H5 端会报错所以需要做平台判断或能力检测否则项目编译到其他端会挂掉。3.2 首页信息流与图片加载分页、下拉刷新、懒加载菜谱首页是整个项目体验的重心结构上我分成了三块顶部轮播图推荐位、分类快捷入口、推荐菜谱瀑布流列表。轮播图用于运营位可以放当季热门菜或活动专题。分类快捷入口用宫格布局点击后跳转到分类页。推荐菜谱列表就是最常见的纵向信息流复用同一个推荐列表接口做分页加载。列表分页实现没什么神秘的onLoad 时请求第一页数据onReachBottom 触底加载下一页onPullDownRefresh 下拉刷新第一页。需要注意的是分页接口必须用 page 和 pageSize 参数返回数据中带上 hasMore 标记。请求完成后用 concat 追加数据同时在下拉刷新和第一次加载时要清空旧数据否则列表会出现重复。图片加载这块有两个独立的问题要处理。第一个是懒加载uniapp 的 image 组件自带 lazy-load 属性打开后能提升滚动场景下的加载性能。第二个是图片尺寸优化。菜谱封面图如果不做裁剪列表直接渲染原图会因为图片太大导致内存暴涨、滑动掉帧。我这边是在后端返回的图片链接上拼了图片处理参数缩略图宽 400 像素详情页再展示原图效果差别非常大。3.3 菜谱详情页的动线设计从食材顺序到步骤引导详情页是菜谱系统的信息承载核心也是整个产品体验好坏的分水岭。我设计的页面结构是从上往下依次是封面大图、标题和基本信息、食材清单、调料清单、步骤列表、推荐菜谱。基本信息栏展示了耗时、难度、分类、热量等元数据用 icon 加文字的小卡片展示。食材和调料做成两个横向卡片区域每一项一行展示名称和用量用户在准备食材时可以对照着挑东西。步骤列表按顺序用大数字序号标识每步包含说明文字和一张配图图片在对应步骤文字上方用户在手机上按顺序滑动就能边看边做。步骤数据的结构用 JSON 数组存储每条包含 step、image、description 三个字段。前端渲染时直接循环数组即可。因为步骤数量一般不超过 10 个不需要做虚拟列表但要注意图片必须懒加载不然页面加载时一次请求太多图片会让详情页变得很慢。页面底部固定了一个操作栏包含收藏按钮、点赞按钮和分享按钮。收藏和点赞的状态在 onLoad 时通过详情接口返回用户点击后先调接口成功后再更新本地状态避免同步问题。这里有一点经验值得提按钮点击后不能只做本地状态反转万一接口请求失败了界面状态和服务器状态就错乱了必须在接口回调里统一更新。3.4 搜索与筛选防抖、历史记录、多条件组合搜索功能是菜谱系统的刚需入口。搜索页我做了三层设计顶部搜索框、历史搜索、热搜词。用户输入关键词后点击搜索按钮进入搜索结果页。搜索框本身有防抖处理。用户输入时不是每敲一个字符就发请求而是等 300 毫秒停顿后再请求避免频繁打接口。这个防抖逻辑用最简单的 setTimeout 就能实现let searchTimer null function onSearchInput(keyword) { if (searchTimer) clearTimeout(searchTimer) searchTimer setTimeout(() { searchRecipe(keyword) }, 300) }搜索结果页支持组合筛选分类、难度、总时长三个维度。筛选条件通过右上角筛选面板选择选择后重新请求列表接口。筛选参数统一拼在 query 里传给后端由 SQL 拼接条件过滤。这个地方的一个坑是筛选面板里的条件重置后要同步清掉列表数据、重置分页页码否则会出现旧数据和筛选结果混在一起的问题。搜索历史记录存本地 storage每次点击搜索结果或确认搜索时把关键词写入历史列表头部超出 10 条就截断。热搜词则走接口获取后端统计最近一周的高频搜索词返回。前者直接 setStorageSync 即可后者要控制请求频率不能每次进入搜索页都请求我给热搜词接口加了一个小时的本地缓存时间。4. 数据模型与接口设计让一套菜谱数据撑起整个系统4.1 表结构怎么设计菜谱、食材、分类、收藏菜谱系统的数据模型不算复杂但设计好坏直接影响后续开发效率。我采用的是关系型数据库设计核心表包括用户表、分类表、菜谱表、收藏表和评论表。这里最核心的是菜谱表。我的做法是把食材清单和步骤说明直接设计成 JSON 字段而不额外拆表。很多人可能会觉得应该规范化拆成食材表、步骤表但实际开发中菜谱的食材和步骤都随着菜谱整体读取不存在单独检索食材的需求拆表反而增加 JOIN 操作。JSON 字段在 MySQL 5.7 中都支持得很好查询性能也不差。CREATE TABLE recipe ( id INT PRIMARY KEY AUTO_INCREMENT, title VARCHAR(100) NOT NULL, cover VARCHAR(500) NOT NULL, category_id INT NOT NULL, difficulty TINYINT DEFAULT 1 COMMENT 1简单 2中等 3困难, cooking_time INT DEFAULT 0 COMMENT 总耗时(分钟), calories INT DEFAULT 0 COMMENT 热量(千卡), ingredients TEXT COMMENT 食材清单 JSON数组, steps TEXT COMMENT 步骤说明 JSON数组, view_count INT DEFAULT 0, like_count INT DEFAULT 0, favorite_count INT DEFAULT 0, status TINYINT DEFAULT 1 COMMENT 0待审核 1已发布 2下架, user_id INT DEFAULT 0 COMMENT 上传者, created_at DATETIME DEFAULT CURRENT_TIMESTAMP, updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP )分类表就简单了id、name、icon、sort 四个字段。收藏表用 userId recipeId 做联合唯一索引避免同一用户重复收藏。评论表包含评论内容、回复关系、点赞数等字段。4.2 接口粒度与请求封装按页面拆分还是按资源拆分接口设计遵循“按页面聚合、按资源拆分”的原则。列表页和详情页需要的数据维度不同接口的设计就不能太碎。我整理的接口清单大致如下GET /api/recipes/home 首页聚合数据包含轮播图和推荐菜谱列表GET /api/recipes/list 分类列表、搜索结果支持分页与筛选GET /api/recipes/detail/:id 菜谱详情含收藏状态、点赞状态POST /api/recipes/favorite 收藏或取消收藏POST /api/recipes/like 点赞或取消点赞POST /api/recipes/create 上传菜谱GET /api/categories 全部分类请求封装是每个小程序项目都要做的事。我在 util 里封装了一个 request 函数统一处理基础 URL、登录态 token、响应码判断和错误提示。function request(options) { return new Promise((resolve, reject) { uni.request({ url: BASE_URL options.url, method: options.method || GET, data: options.data || {}, header: { Content-Type: application/json, Authorization: uni.getStorageSync(token) || }, success: (res) { if (res.data.code 0) { resolve(res.data.data) } else { uni.showToast({ title: res.data.message || 请求失败, icon: none }) reject(res.data) } }, fail: (err) { uni.showToast({ title: 网络异常请稍后重试, icon: none }) reject(err) } }) }) }大部分业务页面都是调用这个封装后的 request 函数而不是直接操作 uni.request这样后续要统一加 token 刷新或者接口埋点只需改这一个文件。4.3 缓存策略本地存储该存什么、存多久小程序缓存用得好页面秒开不是梦。我在这项目里分了三个层级的缓存。第一层是本地缓存用 uni.setStorageSync 实现。首页数据缓存 30 分钟用户再次进入首页时先读缓存缓存过期或下拉刷新才重新请求。分类列表缓存 1 天因为分类基本不变。搜索历史永久存在本地一般不会占太大空间。菜谱详情页缓存 24 小时缓存 key 用 recipe:id 区分过期后自动请求新数据。第二层是接口缓存主要用于详情页。详情页的浏览量和点赞数是动态的全量缓存会影响数据准确性所以我的做法是详情页数据缓存后用户操作收藏、点赞、浏览时先做本地乐观更新再调接口同步同时把本地缓存里的数据更新掉这样后续回看详情页不会出现旧数据。第三层是图片缓存。这里要注意千万不要自己在业务层把图片下载下来再缓存微信开发者工具的 image 组件本身就带有网络图片缓存能力框架层面已经处理了。自己手动缓存图片纯属多此一举还容易把存储空间搞爆。缓存这块还有个容易踩的坑微信小程序本地缓存有上限单个 key 缓存的字符串建议控制在 1MB 以内总缓存 10MB 上限。不要把整页数据原封不动塞进去做业务时只缓存必要字段比如列表页只缓存每道菜的 id、标题、封面、耗时详情页缓存核心字段即可。5. 从开发到上线那些折腾到深夜的坑与优化5.1 开发者工具正常、真机白屏兼容问题的排查链路这个坑几乎每个小程序开发者都遇到过。开发者在工具里预览一切正常一上真机就白屏或者接口报错。我排查这类问题习惯按“三步走”。第一步打开真机调试 vconsole看有没有报错信息。很多问题在真机控制台里一目了然。第二步是在关键位置加 console.log比如 onLoad 开始、请求回调、渲染前逐步缩小范围。第三步是分段注释代码确认是数据层问题还是渲染层问题。我遇到的一次真实案例是iOS 真机上列表页面偶发请求失败率很高开发者工具完全复现不了。后来查看真机日志发现是接口请求同时发出了网络请求和图片下载单条请求触发了微信对并发的限制。解决办法是把列表首屏图片改成懒加载控制并发数这个问题就消失了。另一个常见问题是不支持的新语法。开发者工具默认基础库版本高很多新 API、新语法在旧版微信上不支持。真机白屏前先检查一下项目的编译设置确保 ES6 转 ES5 已开启另外在 manifest 里设置一个合理的最低基础库版本例如 2.10.0 左右。版本设得太高老手机用户进不来设得太低新 API 又用不了。5.2 分享功能与 canvas 海报自定义分享卡片和导出白图菜谱系统天然适合做分享。用户看到一道感兴趣的菜通常会转发给朋友或群聊。这里要用到 onShareAppMessage 生命周期方法。onShareAppMessage() { return { title: this.recipe.title 跟着步骤做超简单, path: /pages/detail/detail?id this.recipe.id, imageUrl: this.recipe.cover } }单是这样配置还不够还需要在 onLoad 里调用 wx.showShareMenu开启右上角菜单分享否则用户无法通过胶囊按钮转发。分享图片用菜谱封面图标题带上菜名和一点引导文案分享率会高一些。canvas 海报就是另一回事了。用户点击“生成海报”后小程序用 canvas 绘制一张包含封面图、二维码、菜名、关键信息的长图方便用户保存后发朋友圈。这里我踩过一个经典坑canvas 绘制网络图片时直接 drawImage 网络地址在小程序环境里是不生效的必须先通过 uni.getImageInfo 获取本地临时路径或者用 uni.downloadFile 下载到本地再绘制。还有一个 iOS 上的老问题canvas 导出白图。搜一下会发现不少人在问我用 uniapp canvas 队列导出时iOS safari 或微信 webview 里生成了空白图片。这个问题的根因在于绘制动作没有完成就调用了导出方法。正确的做法是等 draw 回调触发后再延时导出必要时把导出操作放在 setTimeout 里延迟 100 到 300 毫秒保证 canvas 绘制完全结束。如果图片多建议用队列逐张绘制不要一次并发绘制所有图片。5.3 包体控制与分包加载主包超限后的常规操作微信小程序主包大小限制约 2MB超过就没法上传。菜谱系统功能多、图片素材大很容易超限。我这里的处理思路是“图片全部外链 功能分包”。图片外链很容易理解所有封面和步骤图都放 CDN 或云存储不打包进项目。但注意云存储的域名必须加到 downloadFile 合法域名里否则用户微信里图片会加载失败。功能分包稍微复杂一点。pages.json 里通过 subPackages 字段配置分包结构。我把发布菜谱页、个人中心、评论页这些使用频率较低的页面放进了 subpackages 分包里主包只保留首页、分类页、搜索页、详情页这几个核心页面。这样既满足了包体大小要求又保证了核心功能首屏加载的速度。{ pages: [ pages/index/index, pages/category/category, pages/search/search, pages/detail/detail ], subPackages: [ { root: pagesUser, pages: [ pages/me/me, pages/favorite/favorite, pages/history/history, pages/publish/publish ] } ] }配置完分包后有个细节要注意分包里的页面跳转路径要写全路径比如 /pagesUser/pages/me/me而不是简写。这个路径对了其他都好说路径错了跳转时直接报找不到页面。5.4 上线发布的坑AppID、合法域名、审核类目、年审发布流程走到最后还有一堆琐碎但必须处理的事。首先在 HBuilderX 里点击“发行—小程序—微信”会自动编译生成 dist 目录然后在微信开发者工具里导入这个目录就可以预览和上传代码。选择“上传”后代码会进入微信公众平台的版本管理。上传前要确保 request 合法域名都已经配置。微信要求所有网络请求域名必须是 HTTPS 且完成 ICP 备案不能随便填一个域名就完事。开发时可以不校验上传和线上环境必须校验。审核时容易被忽略的是小程序类目。我最初选的是“工具-信息查询”提交审核后被打回原因是菜谱内容涉及美食内容展示更新应该选“餐饮-美食”或“生活服务”相关类目。后来改成美食类目重新提交就通过了。类目和资质不一致是审核被打回的高频原因提交前先看准再填。最后说一句微信小程序年审。小程序主体信息每年要年审一次年审时会重新核验身份信息和类目要求。项目上线后别忘了这个时间节点年审逾期小程序会被暂停服务这个事比较容易被忽略但影响很大。写在最后整套系统做下来我最大的感受是一个菜谱项目虽然小但五脏俱全。它不只有前端页面还需要把数据结构、接口封装、缓存机制、真机兼容、发布审核整条链路走一遍缺一环都不完整。如果重新做一遍我会优先把菜谱数据的真实性和图片质量做扎实毕竟内容型产品内容不行再好的功能也留不住人。最后分享一个细节所有分享参数里的 imageUrl 必须使用 HTTPS 直链不能是相对路径也不能是 HTTP 链否则 iOS 上分享卡片会显示黑图或空白。这个坑我当时排查了很久希望能帮你直接省掉这一步。