uni-app 跨平台开发专家

技能文档

---
name: uniapp-expert
title: uni-app 跨平台开发专家
category: 开发工具
description: "uni-app 跨平台开发专家：Vue2/Vue3 双版本开发指导、Vue2→Vue3 迁移检查清单与实战方案、微信小程序自动化测试全流程，融合真实项目踩坑经验。当用户开发或迁移 uni-app 项目、编写 Vue3 页面、配置 Pinia，或需要对微信小程序做自动化测试时触发。触发词：uni-app、Vue3 迁移、跨端开发、小程序测试、Composition API。"
---

# uni-app 跨平台开发专家

> uni-app 全栈开发 · Vue2→Vue3 迁移 · 微信小程序自动化测试

## 技能工作流

### 步骤1：识别任务类型

| 用户需求 | 走向 |
|---------|------|
| 开发新页面/组件、Vue3 语法问题 | 按「Vue3 开发指南」作答 |
| Vue2 项目升级、报错排查 | 按「Vue2→Vue3 迁移检查清单」逐项执行 |
| 小程序自动化测试、UI 回归 | 按「小程序自动化测试」流程，详见 [references/weapp-testing.md](references/weapp-testing.md) |

### 步骤2：按对应指南执行

- 开发类：直接按下方 Vue3 指南与规范给出代码方案
- 迁移类：先扫描项目识别 Vue2 特征（生命周期钩子、全局 API、过滤器、`.sync`、Vuex 等），输出迁移检查清单，逐项转换并验证
- 测试类：确认环境准备清单后，编写批量测试脚本一次执行（勿逐条调用）

### 步骤3：验证与交付

- 迁移后验证文件完整性（尤其含 base64 长字符串的样式、复杂 JS 转写）
- 创建的文件验证引用关系；同名 `.min.js` 与 `.js` 区分清楚
- 测试任务输出通过/失败汇总与截图

## Vue3 开发指南

### Composition API vs Options API

| 特性 | Options API | Composition API | 推荐 |
|------|------------|----------------|------|
| 代码组织 | 按选项类型分散 | 按功能逻辑集中 | Composition |
| 逻辑复用 | mixins（隐式） | Composables（显式） | Composition |
| 类型推导 | 较弱 | 强（配合 TS） | Composition |
| 学习曲线 | 简单 | 稍陡 | 新项目用 Composition |

> 建议：新项目使用 Composition API（`<script setup>`），享受更好的类型推导和逻辑复用。

### `<script setup>` 语法糖

```vue
<script setup>
import { ref, computed, onMounted } from 'vue'

// 响应式数据
const count = ref(0)
const doubled = computed(() => count.value * 2)

// 方法
function increment() {
  count.value++
}

// 生命周期
onMounted(() => {
  console.log('组件挂载完成')
})

// 暴露给模板
defineExpose({ count, increment })
</script>
```

**优势**：更少的样板代码、自动推断类型、更好的 Tree-shaking。

### 响应式数据对比

```javascript
// ❌ 错误：丢失响应性
const obj = reactive({ count: 0 })
const { count } = obj  // count 不再是响应式

// ✅ 正确：保持响应性
const obj = reactive({ count: 0 })
const count = toRef(obj, 'count')  // 或
const { count } = toRefs(obj)      // 解构后仍响应式
```

### 开发规范建议

| 规范 | 说明 |
|------|------|
| 响应式数据用 `ref`/`reactive` | 注意 `.value` 与解构丢失响应性问题 |
| 大对象用 `reactive` | 避免 `ref` 解构丢失响应性 |
| Props 定义类型 | 使用 `defineProps` 配合 TypeScript |
| 事件用 `emit` | 清晰定义事件名，建议常量 |
| 组合式逻辑抽离 | 超过 50 行考虑抽成 Composable |
| 避免 `watch` 滥用 | 优先用 `computed` |

## Vue2 → Vue3 迁移检查清单

### 1. 生命周期钩子

| Vue2 | Vue3 | 说明 |
|------|------|------|
| `destroyed` | `unmounted` | Vue 组件生命周期 |
| `beforeDestroy` | `beforeUnmount` | Vue 组件生命周期 |
| `onUnload` | **保留不变** | uni-app 页面生命周期，全平台支持 |

> **重要区分**：uni-app 页面生命周期（onLoad/onShow/onUnload 等）**全部保留**，只有 Vue 组件的生命周期钩子有变化。

### 2. 全局 API

| Vue2 | Vue3 |
|------|------|
| `new Vue()` | `createSSRApp()` |
| `Vue.prototype` | `app.config.globalProperties` |
| `Vue.use()` | `app.use()` |

### 3. 模板语法

| Vue2 | Vue3 | 说明 |
|------|------|------|
| `v-model: value` | `v-model: modelValue` | 默认 model 名 |
| `v-model: input` | `v-model: update:modelValue` | 默认事件名 |
| `slot="xxx"` | `v-slot:xxx` 或 `#xxx` | 具名插槽 |
| `.sync` 修饰符 | `v-model:xxx` | 双向绑定 |
| `v-if` + `v-for` 同一元素 | 分离 | Vue3 v-if 优先级更高 |
| `{{ value \| filter }}` | 计算属性或方法 | 过滤器已移除 |

### 4. 组件选项

| Vue2 | Vue3 |
|------|------|
| 无 | 推荐声明 `emits` 选项 |
| `inheritAttrs: false` | 保留 |
| `functional: true` | 已移除 |

> **选项式 API 兼容性**：Vue2 选项式 API 在 Vue3 中**仍然兼容**。组件逻辑简单、文件较大时直接转换容易出错，建议：①询问用户是否需要转换；②简单页面可保留选项式语法；③复杂页面（多个 mixins、复杂响应式逻辑）才建议转为 Composition API。

### 4.1 Mixins 处理建议

| 场景 | 建议 |
|------|------|
| 简单 mixin（少量 data/methods） | 保留，继续使用 |
| 复杂 mixin（多个生命周期钩子） | 考虑改为 Composables |
| 新增逻辑 | **强烈建议使用 Composables** |

```javascript
// ❌ Mixins（隐式依赖，不清晰）
export default {
  data() { return { count: 0 } },
  methods: { increment() { this.count++ } }
}

// ✅ Composables（显式依赖，更清晰）
import { ref } from 'vue'
export function useCounter() {
  const count = ref(0)
  const increment = () => count.value++
  return { count, increment }
}
```

> 生命周期钩子合并规则（了解即可）：多个 mixin 的同名钩子会**全部调用**，顺序 mixin1 → mixin2 → 组件自身。

### 5. 样式相关

| Vue2 | Vue3 |
|------|------|
| `/deep/` | `::v-deep` 或 `:deep()` |

> **超长字符串处理**：CSS 中 base64 图片、大型 data URI 等超长行，转写时**易截断或格式错误**。转换后必须验证文件完整性，特别是含 `data:image/` 或 `background-image` 的样式。

### 6. 状态管理

| Vue2 | Vue3 |
|------|------|
| Vuex | Pinia |
| `new Vuex.Store()` | `createPinia()` |
| `$store` | `useStore()` |

Pinia 迁移三步闭环：

1. 创建 store（`store/index.js`）
2. 在 `main.js` 中 `app.use(pinia)`
3. 组件中 `import { useStore } from '@/store'`

App.vue 升级要点：使用 `<script setup>`；全局变量改用 Pinia 或独立 globalState.js；应用级生命周期用 `onLaunch`（非 `onMounted`）。

### 7. API 语法

| Vue2 | Vue3 |
|------|------|
| `require/module.exports` | `import/export` |
| `Vue.observable` | `reactive/ref` |
| `this.$listeners` | `this.$attrs` |

> **复杂 JS 转写警告**：涉及复杂闭包、动态 require、循环依赖时，CommonJS → ES Module 转写**容易出错**。建议先人工 review 再决定是否自动转换。

### 8. uni.request 调用方式

```javascript
// 回调方式（Vue2/Vue3 均支持）
uni.request({
  url: 'https://api.example.com',
  success: (res) => { if (res.statusCode === 200) console.log(res.data) },
  fail: (err) => { console.error(err) }
})

// Promise 方式（推荐）
const res = await uni.request({ url: 'https://api.example.com' })
if (res.statusCode === 200) { console.log(res.data) }
```

> 注意：`let [error, res] = await uni.request()` **不是** uni-app 的标准用法，那是 axios 的风格。

### 9. 第三方库

- 检查 `uni_modules` 兼容性
- 检查 `vue.config.js` 配置
- Vue2 语法的第三方组件**标记为无需修复**，不要随意修改

## 小程序自动化测试

完整流程、链式 API 与脚本模板见 [references/weapp-testing.md](references/weapp-testing.md)。核心要点：

1. **环境准备**：开发者工具开启自动化、关闭域名校验、`cli auto` 开启 9421 端口、使用 `dev/mp-weixin` 编译目录
2. **批量执行铁律**：把所有操作写进一个用 `WeappTestRunner` 的 Python 脚本，一次 `python` 调用跑完（逐条调用每步多花 30-60 秒）
3. **选择器**：优先 class 选择器（最稳定）；注意小程序 id 会加前缀
4. 工具脚本在 `scripts/` 目录：`weapp_automation.py`（核心引擎）、`weapp_launcher.py`（启动/关闭开发者工具）、`console_reader.py`（控制台日志）、`test_scenarios.py`（预置场景）

## 项目结构参考

```
uni-app-project/
├── pages/                      # 页面目录
├── components/                  # 公共组件
├── static/                     # 静态资源
├── utils/                      # 工具函数（CommonJS → ES Module）
├── store/                      # Pinia store（Vue3）
│   ├── index.js               # Pinia 实例
│   └── modules/               # Store 模块
├── common/js/                 # 公共 JS
├── uni_modules/               # 第三方模块（Vue2 语法保持不变）
├── App.vue                    # 应用实例
├── main.js                    # 应用入口
├── pages.json                # 页面路由配置
├── manifest.json             # 应用配置
└── vue.config.js            # Vue 配置
```

## 经验教训

1. **文档处理流程**：迁移类文档先提取【易错点】和【注意事项】，转化为【检查清单】，执行任务时同步检查，而不是「读完再检查」
2. **引用关系检查**：创建文件后验证是否被引用、引用的文件是否存在；同名 `.min.js` 与 `.js` 区分清楚
3. **问题排查顺序**：先查文档/日志 → 再查文件引用关系 → 最后才凭经验猜测

## 官方文档

| 资源 | 链接 |
|------|------|
| uni-app 官方文档 | https://uniapp.dcloud.io/ |
| Vue3 官方文档 | https://vuejs.org/ |
| 微信开发者工具 CLI | https://developers.weixin.qq.com/miniprogram/dev/devtools/cli.html |

使用说明

# uni-app 跨平台开发专家

uni-app 全栈开发、Vue2→Vue3 迁移、微信小程序自动化测试一站式指南。

## 使用

```text
帮我把这个 Vue2 的 uni-app 项目迁移到 Vue3
```

```text
给这个小程序写一套自动化冒烟测试
```

## 工作原理

内置 Vue3 开发指南、迁移检查清单（生命周期/全局 API/模板语法/状态管理等 9 大项）与小程序自动化测试工具链。迁移任务按清单逐项转换并验证；测试任务用批量脚本一次跑完并输出汇总报告。

如何安装此技能？

访问技能市场，点击「安装」按钮，按提示将技能包放入 AI 编程助手的 skills 目录即可。