做作品集展示微信小程序这个想法最开始是帮一位摄影师朋友解决作品根本没地方放的尴尬。发百度网盘太廉价发朋友圈画质被压缩自己买个服务器搭网站又贵又难维护。那段时间正好在手头两个小程序项目之间切换就想着干脆用小程序做一个作品集容器既能完整展示图文、视频又能通过小程序码到处分享还不依赖任何第三方平台。项目代号就叫weixin121一套代码跑通了之后我身边好几个做设计、做摄影、做插画的朋友都拿去改了自己的展示页。这篇文章我就把整个项目的完整细节摊开来讲从需求定位、技术选型到自定义导航栏适配、请求封装、缓存策略再到真机调试、审核发布以及从作品集延伸出去的其他场景。里面每一条都是实际跑过的路不是概念搬砖。1. 作品集展示小程序需求定位与信息架构1.1 作品集场景的真实痛点先别急着写代码先想清楚这类小程序到底在解决什么问题。作品集展示的核心诉求有三个第一是专业感作品需要分类清晰、排版干净能看出作者的审美和功底第二是分享友好发给客户、发给面试官、贴到社交平台对方点开就能看不需要下载安装第三是低成本维护作品更新频率不低后端要尽可能简单甚至可以用现成的云开发。微信小程序恰好都能满足。小程序码天生适合分享微信内置浏览器打开即用加载速度体感上比H5更接近原生而且个人开发者在微信公众平台注册一个小程序不需要服务器也能用云开发跑起来。这类小程序的信息架构基本是一个标准的三层结构首页作品卡片流按最新时间或热度排序顶部放分类筛选列表/分类页按系列、按年份、按类型切换详情页大图预览、作品说明、作者信息、联系方式。如果作品量大还要加一个搜索入口。我实际做的第一版页面比这个多加了关于我独立页和服务报价页最后发现太多余了作品集的核心路径就是浏览分类-点开作品-联系作者其他都是噪音。有四五个页面的小程序和有两三个页面的小程序维护成本完全不一样砍掉次要页面是值得的。1.2 页面结构的设计取舍我在weixin121项目里最终保留的页面是首页作品流分类筛选、详情页图片/视频展示联系按钮、关于页作者简介作品数量联系信息。底部TabBar只有两个首页和关于。首页的布局用了瀑布流双列这是作品集最常见的样式视觉密度高也符合刷作品的浏览习惯。双列的坑在于图片高度不一致如果重新计算每张卡片的绝对位置代码复杂度会上升。我在项目里用的是更省心的做法两列flex布局图片高度交给css的widthFix模式自适应每张卡片的底部内容标题、分类标签对齐视觉上不追求严丝合缝但要保证两列高度差不要超过一个卡片的高度太多。这里的重点是作品集展示类的项目页面数量、交互复杂度都要为展示效率服务不要做花哨的动效不要在详情页里塞列表页的逻辑。用户要看的是作品不是你的开发技能。2. 技术选型原生小程序、uniapp还是Vue转小程序2.1 三条主流路线的真实差异做小程序第一件事就是选技术栈。现在主流的三条路是原生小程序、uniapp跨端框架、以及Taro这类把Vue/React代码编译成小程序的方案。我列个表给你看清它们的差异维度原生小程序uniappTaroVue/React转小程序开发语言WXML/WXSS/JS JSONVue语法Vue/React语法上手成本需要重新学一套标签和API会Vue就能写会Vue/React就能写性能和包体积最直接无中间层框架层有额外运行时开销编译期转化有运行时适配层多端支持仅微信小程序可出App、H5、其他小程序可出H5、React Native等多端调试体验开发者工具最顺畅、出错好定位跨端调试要逐端验证端差异较难排查报错堆栈有转换层适合项目功能简单、追求极致性能和稳定性明确要覆盖多端的中型项目团队已有Vue/React技术栈且要跨端网上很多人说用uniapp一套代码通吃App、小程序、H5这句话只对了一半。uniapp确实能出多端但你一旦开始用某端独有的能力比如微信小程序的原生组件、支付、订阅消息代码里就会出现大量条件编译跨端代码并不是完全复用的。我在weixin121里最后选的是原生小程序原因很简单作品集展示功能不复杂页面就三五个原生开发没有任何框架包袱出问题的概率最低。如果你做的是一个复杂度高、明确要覆盖安卓/iOS/鸿蒙等多端的产品那uni-app或Taro才有选的价值。真要做跨端也要在项目初期就把哪些逻辑可以跨端、哪些必须端内定制划干净。2.2 Vue项目如何发布微信小程序到底怎么理解搜索词里vue项目如何发布微信小程序热度很高这个问题的前提其实有点问题。普通Vue项目是一个运行在浏览器里的单页应用SPA它依赖DOM、依赖浏览器API而微信小程序运行在自己的渲染引擎里用的是WXML标记语言两者根本不是一个容器。所以不是把Vue项目发布成小程序而是用Vue语法写一套小程序这就是uniapp和Taro在做的事。如果你手上已经有一个Vue的Web作品集站指望直接打包成小程序是不可能的你必须把页面重新实现一遍——列表页、详情页、图片预览这些在小程序里都有自己的原生组件。我见过不少人栽在这一点上拿着Vue的组件库、路由方案往小程序框架里套最后发现小程序没有DOM节点概念、没有window对象、没有真正的history路由所有页面都要基于app.json的页面配置来组织。选型的本质不是哪个框架厉害而是你打算在哪个运行时上运行你的业务。想清楚这个就不会再纠结能不能直接把Vue项目发小程序了。2.3 工程初始化与目录规划weixin121的目录结构很典型按功能划分模块weixin121/ ├─ app.js ├─ app.json ├─ app.wxss ├─ pages/ │ ├─ home/ # 首页作品流 分类筛选 │ ├─ detail/ # 作品详情页 │ └─ about/ # 关于页 ├─ components/ │ ├─ work-card/ # 作品卡片 │ └─ custom-navbar/ # 自定义导航栏 ├─ utils/ │ ├─ request.js # 请求封装 │ ├─ cache.js # 缓存策略 │ └─ nav.js # 导航栏高度计算 └─ images/ # 本地静态资源这里有个很关键的点把自定义导航栏从app.json的全局配置里剥离出来做成组件而不是每个页面各写一份。后面你会看到导航栏的适配逻辑很琐碎做成组件后全项目只有一个地方需要维护。同理请求、缓存、工具函数都隔离在utils里页面代码就只管渲染和事件。3. 自定义顶部导航栏高度最容易被忽略的适配硬仗3.1 为什么默认导航栏不够用微信小程序的默认导航栏只能改标题和背景色导航栏上放不了其他按钮也无法做成毛玻璃效果、透明渐变这种视觉设计。作品集类项目对首屏视觉要求很高默认导航栏一眼就能看出是套模板的我直接把app.json里的页面设置为navigationStyle: custom全站换用自研custom-navbar组件。换来的代价就是你必须自己处理所有手机机型的顶部安全区域。状态栏高度不一样胶囊按钮右上角那个...和○的位置不一样刘海屏、灵动岛、安卓全面屏胶囊的位置也各不相同。很多项目卡在这里顶部导航栏要么和胶囊重叠要么在部分机型上顶到屏幕外面。3.2 高度计算的标准公式导航栏适配的原理其实不复杂。微信把屏幕最上面的状态栏显示电量、时间的那条高度暴露给了开发者胶囊按钮的位置也能通过API拿得到。自定义导航栏的总高度由两部分组成状态栏高度 胶囊按钮垂直位置相对状态栏底部的距离。计算公式如下// utils/nav.js const getNavInfo () { // 基础库 2.20.1 起推荐用 getWindowInfo const windowInfo wx.getWindowInfo(); const menuRect wx.getMenuButtonBoundingClientRect(); const statusBarHeight windowInfo.statusBarHeight; // 胶囊按钮顶部到屏幕顶部的距离 减去 状态栏高度得到胶囊距状态栏底部的距离 const menuTop menuRect.top - statusBarHeight; // 自定义导航栏高度 状态栏高度 (胶囊顶部距状态栏底部距离 * 2) 胶囊高度 const navBarHeight statusBarHeight menuTop * 2 menuRect.height; // 导航栏内容区域的可用高度 const contentHeight menuTop * 2 menuRect.height; return { statusBarHeight, navBarHeight, contentHeight, menuRect }; };这个公式里的menuTop * 2是什么意思胶囊按钮在垂直方向上并不是居中于状态栏下方的一整条区域而是有自己的上下边距。微信官方设计习惯是胶囊上方和下方各留一个menuTop的间距所以导航栏在状态栏之外还需要menuTop * 2 菜单按钮高度这段空间整体看起来才协调。getMenuButtonBoundingClientRect拿到的是胶囊相对于屏幕左上角的坐标把menuTop算出来之后无论是安卓还是iOS只要这两组数据是准的布局就不会歪。3.3 真机适配的细节我在开发和真机调试中碰到过几个导航栏相关的坑逐个说自定义导航栏组件要预留状态栏占位组件最外层盒子的padding-top必须等于statusBarHeight否则内容会顶进状态栏。这个占位要在WXML里用内联样式绑定动态值不能在wxss里写死。胶囊按钮是只读区域你不能覆盖到胶囊按钮上面但你的导航栏容器高度足够时自定义的返回按钮要放在胶囊按钮左侧水平方向上和它对齐垂直方向上居中这样视觉上最自然。下拉刷新层级如果用了enablePullDownRefresh自定义导航栏不会自动避让刷新动画刷新时的三个点动画会被导航栏遮住一部分建议优先用onPullDownRefreshwx.startPullDownRefresh配合或者在页面顶部留出足够空间。全面屏安全区底部也要适配尤其是详情页的联系作者悬浮按钮要用env(safe-area-inset-bottom)做底边距不然iPhone底部横条会压住按钮。导航栏这块没有技术深度的门槛纯粹是细节活。我的经验是早点在真机上多机型测试不要只在开发者工具里看。开发者工具的模拟器和真机对状态栏、胶囊的渲染是有偏差的。weixin121项目实测在iPhone 8、iPhone 14 Pro和几台安卓机型上表现一致靠的就是真机调试阶段反复校准。4. 数据层设计请求封装、缓存策略与平台能力适配4.1 请求封装统一入口别让每个页面各写一遍小程序页面多了之后网络请求如果不收敛维护成本会直线上升。作品集项目虽然业务后端简单通常就几个列表和详情接口但也要有一套统一的请求封装这样日志、错误处理、loading控制都在同一个地方。我的request封装核心逻辑是这样的// utils/request.js const BASE_URL https://api.example.com; const request (options) { return new Promise((resolve, reject) { wx.request({ url: BASE_URL options.url, method: options.method || GET, data: options.data || {}, timeout: options.timeout || 10000, header: { Content-Type: application/json, // 登录态从缓存读取不散落在页面里 Authorization: wx.getStorageSync(token) ? Bearer ${wx.getStorageSync(token)} : }, success(res) { if (res.statusCode 200 res.statusCode 300) { // 后端约定 code 0 为业务成功 if (res.data res.data.code 0) { resolve(res.data.data); } else { wx.showToast({ title: res.data.msg || 请求失败, icon: none }); reject(res.data); } } else if (res.statusCode 401) { // 登录态失效跳转登录或重新静默登录 wx.removeStorageSync(token); reject(new Error(登录已过期)); } else { wx.showToast({ title: 请求错误(${res.statusCode}), icon: none }); reject(res); } }, fail(err) { wx.showToast({ title: 网络异常请检查网络, icon: none }); reject(err); } }); }); }; module.exports { request };几个容易被忽略的点loading和请求计数如果两个请求同时发起各自调wx.showLoading第一个结束就把loading关了第二个还在跑但loading已经消失。正确做法是维护一个pendingCount变量所有请求pendingCount每个请求完成时pendingCount--只在pendingCount归零时关loading。作品集首页通常同时拉分类和作品列表这个坑很容易踩到。状态码和业务码分开处理HTTP 200不代表业务成功后端返回code ! 0时不应该走到resolve分支。很多新手直接把整个res给页面页面再去猜成功失败这是不对的。并发和顺序如果详情页需要拉作品详情 拉作者信息两个接口别用回调嵌套用Promise.all两个请求同时发都返回后再渲染。4.2 缓存策略2小时刷新还是强制刷新作品集的数据特点很明确更新不频繁通常几天才发一个新作品但首屏加载速度直接影响用户会不会继续往下滑。我用缓存策略把首屏先渲染出上次的缓存数据再在背后请求最新数据数据到达后再替换。网上很多人讨论微信小程序缓存时间怎么设置其实小程序没有全局配置项一句话解决要自己写缓存过期逻辑也就是用wx.setStorageSync存数据时附带时间戳读取时判断是否过期。// utils/cache.js const CACHE_PREFIX weixin121_cache_; const setCache (key, data, maxAge 2 * 60 * 60 * 1000) { wx.setStorageSync(CACHE_PREFIX key, { data, time: Date.now(), maxAge }); }; const getCache (key) { const cache wx.getStorageSync(CACHE_PREFIX key); if (!cache) return null; const expired Date.now() - cache.time cache.maxAge; return expired ? null : cache.data; }; // 使用示例页面 onLoad 时先取缓存 const cachedList getCache(work_list_home); if (cachedList) { this.setData({ works: cachedList }); } // 再请求最新数据成功后 setCache 并重新 setData这里的细节是缓存不能和用户主动刷新打架。我在首页顶部加了一个下拉刷新图标点击后强制绕过缓存直接请求成功后更新缓存并提示已是最新内容。如果你的后台有运营后台发作品建议再做一个发布新作品时让客户端主动失效缓存的机制最简单的是用一个version字段请求时带上后端版本不一致就强制拉新。4.3 平台能力适配chooseavatar权限和need sign info新的基础库中头像昵称填写能力改成了头像选择器和昵称输入框的组合按钮需要声明open-typechooseAvatar并且在小程序管理后台的隐私协议中声明收集用户头像昵称。这个能力我在关于页的访客留言里用过但作品集展示场景其实完全没有必要强制用户授权头像昵称。我用的是一个纯文字留言表单用户可以直接提交留言省掉了一个巨大的隐私合规步骤。至于need sign info这是支付和复杂业务接口里会遇到的签名参数需求。作品集展示通常不走支付我遇到这个词是在做扩展功能调研的时候微信支付新版本要求服务端在调起支付时返回signInfo字段如果不做支付业务这个字段和你无关。但如果你以后想做付费下载作品、付费咨询就必须了解不要等支付配置时才手忙脚乱。5. 开发中踩过的坑与解决方案实录5.1 图片提取与大图加载内存和体验的双重压力作品集的核心资产是图片图片加载的坑几乎躲不掉。微信小程序里加载高清大图内存占用会快速增长尤其是详情页的轮播图用swiper时如果同时渲染多张原图低端安卓机很容易白屏或退到后台被系统杀掉。我的实践方案分三层列表页缩略图后端在返回列表时给出压缩后的URL通常压到600px宽左右卡片上用modewidthFix让高度自适应同时给image组件加lazy-load属性只加载视口附近的图片详情页原图swiper里用wx.previewImage实现点击放大返回后swiper先只渲染当前索引附近的前后两张图其他图等用户滑动到当前索引再设置数据源图片预加载详情页提前wx.preloadPage不行的话可以把图片数组的URL提前new Image()是浏览器用法小程序里没有Image对象需要通过wx.getImageInfo来触发缓存但这个方法有并发上限所以我说的是控制并发——详情页一次最多getImageInfo三张避免并发拉取十张造成网络和内存峰值。关于图片提取这个词我在做作品集时也遇到过用户从相册选图上传用wx.chooseMedia获取临时文件路径再通过wx.uploadFile传到后端CDN。注意wx.chooseMedia返回的临时路径只在本次会话有效一定要在页面销毁前完成上传否则路径会失效。5.2 长列表渲染list-builder和虚拟滚动的使用感受作品集列表数量多的时候普通wx:for直接在页面上渲染一百个卡片滚动起来明显掉帧。小程序的wx:for没有天然的虚拟滚动能力所有节点都会一次性加入到渲染树中。微信官方后来推出了list-builder组件思路是通过节点复用机制只渲染当前可视区和预加载区域内的项目在滚动时动态回收和复用节点减少setData和渲染层压力。我在作品集列表超过80条的真实场景里做了对比普通wx:for渲染80个卡片初次加载到可滚动的时间约为1.8秒滚动时有明显卡顿用list-builder之后初次渲染时间降到0.9秒左右滚动流畅度明显提升。不过list-builder使用细节不少它需要明确指定每一项的固定模板和key动态高度卡片比如瀑布流里高度不固定的图适配起来没有普通wx:for方便必须配合setData的分片提交一次不要push整个大数组不然仍然会有渲染卡顿如果作品列表总量不超过50个没必要强行用它普通列表就行别为了技术而技术。5.3 单选框和自定义表单组件作品集项目里通常会有联系表单比如留言、报价咨询。这里绕不开表单组件。微信小程序的原生radio-group和radio样式偏基础在安卓和iOS上视觉差异明显。我在项目里直接把单选做成一个样式统一的check-box图标按钮组没有用原生radio组件view classradio-group view classradio-item {{selected item.value ? active : }} wx:for{{radioOptions}} wx:keyvalue bindtaponRadioTap >