uni-app 小程序开发 Skill
本 Skill 提供开发微信小程序的专业知识、编码规范与可复用模板，覆盖 Vue2 与 Vue3 两种语法体系。遵循本 Skill 产出的代码应规范、可维护、跨端兼容，可直接用于商业项目。
适用场景
在以下情况下使用本 Skill：
- 从零创建 uni-app 小程序项目（Vue2 或 Vue3）
- 新增/修改页面、自定义组件、公共方法
- 封装网络请求、本地存储、工具函数
- 处理路由跳转、生命周期、条件编译、平台差异
- 使用 uni 组件与 uni API 实现业务功能
- 构建状态管理（Vuex / Pinia）
- 上架发布前的代码规范审查
核心原则
- 先确认语法版本：动手编码前，先判断项目使用 Vue2 还是 Vue3 语法（通过
manifest.json或package.json判断），严格遵循对应语法，禁止混用。 - 遵循 uni-app 规范：使用 uni 提供的组件与 API，而非平台专属（如 wx. 直接调用），以保证多端可编译。
- 组件化与复用：遵循页面-组件分层，业务组件放入
components，公共逻辑抽取为composables（Vue3）或mixins（Vue2）。 - 跨端兼容：涉及平台差异时使用条件编译注释
#ifdef/#ifndef。 - 代码整洁：遵守命名规范、目录结构、注释规范，产出可维护代码。
工作流程
1. 识别项目环境
开始前先检查项目配置，判断技术栈：
- 读取
manifest.json：查看vueVersion字段（"2"为 Vue2，"3"为 Vue3） - 读取
package.json：查看dependencies是否含@dcloudio/uni-app（Vue3 使用vue@3与@dcloudio/uni-app新版依赖） - 检查页面入口：
main.js（Vue2 使用Vue+App，Vue3 使用createSSRApp）
将判断结果作为后续所有代码编写的依据。
2. 参考对应语法文档
根据项目版本加载对应参考文档：
- Vue2 语法：读取
references/vue2-syntax.md - Vue3 语法：读取
references/vue3-syntax.md
3. 遵循组件与项目规范
- 编写组件前阅读
references/component-guide.md - 涉及项目结构、命名、目录组织时阅读
references/project-structure.md - 涉及网络、存储、路由、平台 API 时阅读
references/api-guide.md
4. 编写代码
严格遵循文档中的语法模板与规范示例。如需快速生成页面/组件骨架，可参考 assets/ 下的模板文件。
关键知识速查
目录结构（标准 uni-app 项目）
project-root/
├── pages/ # 页面目录，每个页面一个文件夹
│ └── index/
│ ├── index.vue # 页面逻辑与模板
│ └── index.scss # 页面样式
├── components/ # 自定义组件
├── composables/ # Vue3 组合式函数（hooks）
├── mixins/ # Vue2 混入
├── store/ # 状态管理（Vuex/Pinia）
├── utils/ # 工具函数
│ └── request.js # 网络请求封装
├── static/ # 静态资源
├── pages.json # 页面路由与配置
├── manifest.json # 应用配置
├── App.vue # 应用入口组件
├── main.js # 入口文件
└── uni.scss # 全局 SCSS 变量
生命周期对比
| 场景 | Vue2（Options API） | Vue3（Composition API） |
|---|---|---|
| 组件创建 | created() |
setup() / onLoad |
| 组件挂载 | mounted() |
onMounted() |
| 页面加载 | onLoad(options) |
onLoad((options) => {}) |
| 页面显示 | onShow() |
onShow(() => {}) |
| 页面隐藏 | onHide() |
onHide(() => {}) |
| 组件卸载 | beforeDestroy() |
onBeforeUnmount() |
常用 uni API
// 页面跳转
uni.navigateTo({ url: '/pages/detail/detail?id=1' })
uni.redirectTo({ url: '/pages/login/login' })
uni.navigateBack({ delta: 1 })
uni.switchTab({ url: '/pages/home/home' })
// 数据存储
uni.setStorageSync('key', value)
const v = uni.getStorageSync('key')
uni.removeStorageSync('key')
// 交互反馈
uni.showToast({ title: '操作成功', icon: 'success' })
uni.showLoading({ title: '加载中' })
uni.hideLoading()
uni.showModal({ title: '提示', content: '确认删除？' })
// 路由参数获取
// 页面 onLoad 中接收：onLoad(options) => options.id
注意事项与陷阱
- Vue3 中慎用
this：在<script setup>组合式 API 中不存在this，须使用响应式变量与函数。 - 页面级生命周期：
onLoad/onShow等页面生命周期仅在页面组件中有效，组件内不可用。 - 样式单位：rpx 是响应式单位，
750rpx= 屏幕宽度。样式尽量使用 rpx 保证不同机型适配。 - 模板语法：Vue3 小程序端使用
v-model语法与 Web 端存在差异，需按参考文档处理。 - 条件编译：平台差异代码用注释包裹：
// #ifdef MP-WEIXIN // 仅微信小程序执行 // #endif - 组件标签名：自定义组件使用 kebab-case（短横线），如
<custom-button>。 - 禁止直接混用
wx.：优先使用uni.API，必要时才配合条件编译使用平台 API。
