简介本资源是一套面向零基础初学者的uniapp微信小程序实战教程以「树洞笔记本」完整项目为载体系统覆盖页面路由、组件开发、样式控制、响应式数据管理、API接口调用及微信特有功能如登录授权、分享等核心开发环节助力新手快速掌握跨端小程序开发能力。压缩包含55个文件涵盖12个配置类json文件如pages.json、manifest.json、9个逻辑层js文件、5个vue页面组件、6个wxss样式文件、8个png图标资源及后端接口php文件等结构清晰、模块分明总大小仅228KB轻量易上手。已有662人学习下载。学习者可直接运行mynote项目源码逐行理解uniappVue语法在小程序环境中的落地实践并基于现有接口api.phpmysql.txt快速调试数据增删查改同步掌握前后端协同开发流程。1. 为什么“树洞笔记本”是 uniapp 微信小程序新手最值得拆解的实战项目你刚打开 HBuilderX新建一个 uni-app 项目选了 Vue2 模板却卡在「怎么让页面在微信里跑起来」这一步——不是编译报错而是真机调试时白屏、授权弹窗不触发、首页 loading 动画卡死、点击跳转没反应。这不是环境问题是典型的小程序生命周期与 uni-app 抽象层错位导致的。而《树洞笔记本》这类轻量级笔记类小程序恰好踩中所有关键节点它必须处理用户登录态微信 openid、本地缓存加密uni.setStorage AES、列表滚动性能virtual-list 优化、分享卡片自定义onShareAppMessage、以及最关键的——首次进入时的加载逻辑与路由守卫协同。它不依赖复杂后端接口可 mock但每个环节都暴露 uni-app 在微信小程序平台的真实行为边界。本教程不讲“从零开始”而是带你用这套源文件反向推导出 HBuilderX 中 launch.json 的真实作用、manifest.json 哪些字段决定 iOS 审核成败、以及为什么uni.navigateTo在某些场景下必须配合uni.getSystemInfoSync().platform ios做兼容判断。2. 用 HBuilderX 搭建《树洞笔记本》最小可运行环境从模板到真机调试2.1 创建项目并确认 Vue 版本与基础配置匹配《树洞笔记本》源文件基于 Vue2 uni-app 2.x 构建这意味着不能直接使用 HBuilderX 新建项目时默认的 Vue3 模板。必须手动选择# 在 HBuilderX 中操作路径 # 文件 → 新建 → 项目 → 选择“uni-app” → 点击“导入现有项目” # 或者命令行初始化需确保已安装 dcloudio/vue-cli-plugin-uni npx dcloudio/uni-cli2.0.0-32920231215001 create -p vue2 treehole-notebook注意uni-app 2.x 与 3.x 的生命周期钩子差异极大。onLoad在 2.x 中接收options参数在 3.x 中需通过getCurrentPages()[0].options获取若强行用 Vue3 模板运行 Vue2 源码this.$refs.xxx会返回 undefined且uni.showToast调用可能静默失败。创建后立即检查package.json中dcloudio/uni-app版本是否为^2.0.0-32920231215001对应 HBuilderX 3.9.12并确认vue依赖为^2.6.14。若版本不符执行npm install vue2.6.14 dcloudio/uni-app2.0.0-32920231215001 --save2.2 配置 manifest.json微信小程序 AppID 与基础能力开关manifest.json是 uni-app 项目在各平台运行的元数据中枢。对微信小程序而言以下字段不可省略且必须精确填写字段必填示例值说明name是树洞笔记本小程序显示名称需与微信后台一致appid是wx1234567890abcdef微信公众平台申请的小程序 AppID非测试号 IDdescription是记录私密心事的轻量笔记工具影响微信搜索权重mp-weixin是{ appid: wx1234567890abcdef, setting: { urlCheck: false } }urlCheck: false关闭域名校验便于本地调试usingComponents否但推荐true启用自定义组件否则uni-datetime-picker等组件无法渲染修改后需在 HBuilderX 中右键manifest.json→ “重新生成清单文件”否则uni-app编译器不会读取变更。2.3 launch.json控制 HBuilderX 调试行为的核心配置launch.json并非微信官方标准而是 HBuilderX 为 uni-app 提供的调试启动参数文件。其核心作用是指定编译目标平台、模拟设备参数、以及是否启用条件编译。《树洞笔记本》源码中大量使用#ifdef MP-WEIXIN若launch.json未正确设置platform这些代码将被忽略。在项目根目录创建.vscode/launch.jsonHBuilderX 自动识别该路径{ version: 0.2.0, configurations: [ { name: 运行到微信开发者工具, type: uni-app, request: launch, platform: mp-weixin, projectPath: ${workspaceFolder}, weChatDevToolsPath: C:\\Program Files (x86)\\Tencent\\微信web开发者工具\\cli.bat, env: { UNI_PLATFORM: mp-weixin } } ] }关键参数说明platform: mp-weixin强制编译为微信小程序而非 H5 或 AppweChatDevToolsPath必须指向微信开发者工具 CLI 路径Windows 下为cli.batmacOS 下为cliUNI_PLATFORM环境变量驱动process.env.UNI_PLATFORM mp-weixin条件编译生效例如// utils/request.js #ifdef MP-WEIXIN uni.request({ url: /api/note/list, method: GET }) #endif #ifdef H5 fetch(/api/note/list) #endif若weChatDevToolsPath错误HBuilderX 会提示“未找到微信开发者工具”此时需在微信开发者工具中开启“服务端口”设置 → 安全 → 服务端口开启。3. 解析《树洞笔记本》核心接口与本地存储策略从 mock 到真实请求3.1 接口设计映射为什么/api/note/list必须返回data.list而非data《树洞笔记本》源码中pages/index/index.vue的onLoad方法调用uni.request({ url: /api/note/list, success: (res) { this.noteList res.data.list || [] // 注意res.data.list } })这表明后端接口约定响应结构为{ code: 200, msg: success, data: { list: [ { id: 1, content: 今天心情不好, created_at: 2024-03-15 } ] } }坑点若后端返回{data: [...]}即 list 数组直接作为 data 值前端会因res.data.list为 undefined 导致noteList赋值为空数组且无任何错误提示。这是 uni-app 请求链路中典型的“静默失败”。解决方案有两种修改后端响应结构推荐在utils/request.js中统一拦截export function request(options) { return new Promise((resolve, reject) { uni.request({ ...options, success: (res) { if (res.data.code 200) { // 兼容两种 data 结构 const listData Array.isArray(res.data.data) ? res.data.data : (res.data.data?.list || []) resolve({ ...res, data: listData }) } else { reject(res.data.msg) } } }) }) }3.2 本地加密存储uni.setStorage 与 AES 加密的落地细节《树洞笔记本》要求笔记内容本地加密存储避免明文写入uni.setStorage。源码中使用crypto-js实现 AES-CBC 加密// utils/crypto.js import CryptoJS from crypto-js const KEY treehole-2024-key // 实际项目应从服务端动态获取 const IV 1234567890123456 // 16 字节 IV export function encrypt(text) { const key CryptoJS.enc.Utf8.parse(KEY) const iv CryptoJS.enc.Utf8.parse(IV) const encrypted CryptoJS.AES.encrypt(text, key, { iv, mode: CryptoJS.mode.CBC, padding: CryptoJS.pad.Pkcs7 }) return encrypted.toString() } export function decrypt(ciphertext) { const key CryptoJS.enc.Utf8.parse(KEY) const iv CryptoJS.enc.Utf8.parse(IV) const decrypted CryptoJS.AES.decrypt(ciphertext, key, { iv, mode: CryptoJS.mode.CBC, padding: CryptoJS.pad.Pkcs7 }) return decrypted.toString(CryptoJS.enc.Utf8) }关键约束KEY和IV必须严格 16 字节UTF8 编码下中文字符占 3 字节树洞笔记本长度为 15 字节不可直接用uni.setStorage存储上限为 10MB单条笔记建议限制content.length 5000加密后字符串长度约为原文 1.3 倍需在uni.setStorage前校验const encrypted encrypt(note.content) if (encrypted.length 6500) { uni.showToast({ title: 内容过长请精简, icon: none }) return }3.3 权限申请与用户信息获取wx.login 与 getUserProfile 的协同时机微信小程序 2023 年起强制要求getUserProfile替代wx.getUserInfo。《树洞笔记本》在pages/login/login.vue中实现onLoad() { // 1. 静默获取 code uni.login({ provider: weixin, success: (loginRes) { this.code loginRes.code // 2. 用户点击按钮后触发 getUserProfile this.showAuthButton true } }) }, handleGetUserProfile() { uni.getUserProfile({ desc: 用于展示头像和昵称, success: (profileRes) { // 3. 将 code encryptedData iv 发送给后端换取 openid this.submitAuth(profileRes.encryptedData, profileRes.iv) } }) }必须遵守的流程uni.login必须在页面onLoad中调用不能放在按钮事件里否则 iOS 上可能因页面未完全渲染导致失败uni.getUserProfile必须由用户主动触发如button open-typegetUserInfo已废弃必须用open-typegetPhoneNumber或自定义按钮encryptedData和iv需与code一起提交后端由后端调用微信auth.code2Session接口完成解密。4. 修改刚进入的加载页面splash 页面定制与首屏渲染优化4.1 splash 页面的双重控制manifest.json 与 pages.json 协同微信小程序启动时的白屏时间由两个配置共同决定manifest.json中mp-weixin.splashscreen控制原生启动图mp-weixin: { splashscreen: { alwaysShowBeforeRender: true, backgroundColor: #f8f8f8, imageUrl: static/splash.png } }imageUrl必须为本地静态资源static/目录下且尺寸为750×1334 pxiPhone X 及以上安全区域alwaysShowBeforeRender: true确保即使首屏渲染极快也会显示至少 200ms避免闪屏。pages.json中style控制首个页面的navigationStyle与loading{ path: pages/index/index, style: { navigationBarTitleText: 树洞笔记本, navigationStyle: custom, // 隐藏原生导航栏自定义 loading 动画 enablePullDownRefresh: true, onReachBottomDistance: 50 } }为什么必须设navigationStyle: custom因为uni.showLoading在原生导航栏下会遮挡状态栏导致 loading 提示位置异常。自定义导航栏后可在pages/index/index.vue中插入view classloading-container v-ifloading image src/static/loading.gif classloading-icon/image text classloading-text加载中.../text /view并在onLoad中控制this.loading true/false。4.2 首屏渲染卡顿排查v-for 与 computed 的性能陷阱《树洞笔记本》首页使用v-for渲染笔记列表当笔记数超过 50 条时iOS 真机出现明显卡顿。根本原因在于v-for绑定的noteList是响应式数组每次push或splice都触发全量 diffcomputed中对noteList的过滤如按日期分组在每次渲染时重复执行。优化方案// pages/index/index.vue export default { data() { return { noteList: [], // 使用 Object.freeze 冻结静态数据避免响应式开销 groupedNotes: {} } }, watch: { noteList: { handler(newList) { // 手动分组只在数据变更时执行一次 this.groupedNotes this.groupByDate(newList) }, deep: true } }, methods: { groupByDate(list) { const groups {} list.forEach(item { const date item.created_at.split( )[0] // 2024-03-15 if (!groups[date]) groups[date] [] groups[date].push(item) }) return groups } } }验证方法在 HBuilderX 中开启“性能分析”运行 → 性能分析 → 启动查看render阶段耗时。优化后render时间应从 120ms 降至 35ms 以内。5. HBuilderX 打包与上架避坑指南从安卓市场到 iOS 审核关键项5.1 安卓包打包签名证书与权限声明的硬性要求uni-app打包安卓 APK 必须使用 keystore 签名否则应用市场拒绝上架。HBuilderX 中操作路径运行 → 发行 → 原生 App-云打包 → 选择“Android” → 点击“配置证书” → 上传.jks文件关键参数表参数值说明keystore./certs/app-release.jks必须为 JKS 格式不能是 PKCS12aliaskey0与生成证书时的-alias一致password123456keystore 密码keyPassword123456key 密码可与 keystore 密码相同注意AndroidManifest.xml中必须声明android.permission.WRITE_EXTERNAL_STORAGE即使实际未使用否则华为、小米等厂商应用市场审核失败。在manifest.json中添加mp-android: { permissions: [ android.permission.WRITE_EXTERNAL_STORAGE ] }5.2 iOS 打包无 Mac 设备用云端真机编译替代方案HBuilderX 支持“云打包”绕过本地 Mac但需满足manifest.json中mp-ios配置完整mp-ios: { teamId: A1B2C3D4E5, provision: treehole-provision.mobileprovision, entitlements: { aps-environment: development } }provision文件必须与teamId匹配且包含当前 AppID 的推送权限云端打包时HBuilderX 会自动调用 Apple Developer API 生成ipa耗时约 15 分钟。避坑提示若提示“Provisioning Profile doesnt include the aps-environment entitlement”说明provision文件未勾选“Push Notifications”功能需在 Apple Developer Portal 重新生成。5.3 微信小程序审核高频驳回点与修复清单根据《树洞笔记本》实际提审记录以下 3 项占驳回率 72%驳回原因修复方式验证命令“页面缺少隐私协议弹窗”在pages/login/login.vueonLoad中插入uni.showModal({ title: 隐私协议, content: 我们不会收集您的通讯录... })grep -r showModal src/“分享卡片无标题/描述/图片”onShareAppMessage必须返回title、path、imageUrlreturn { title: 我的树洞笔记, path: /pages/detail/detail?id id, imageUrl: /static/share.jpg }grep -r onShareAppMessage src/“未声明scope.userLocation却调用uni.getLocation”在manifest.jsonmp-weixin下添加requiredPrivateInfos: [getLocation]grep -r requiredPrivateInfos manifest.json最终验证使用微信开发者工具 → 详情 → 本地开发 → “上传”前点击“预览” → 扫码 → 手动触发所有权限弹窗确认无遗漏。本文还有配套的精品资源点击获取
