# uni-app X 迁移操作总结

## 操作日期
2024年（具体日期根据实际情况填写）

## 操作背景
项目需要从传统的 uni-app 迁移到 **uni-app X**，以支持 `.uvue` 文件在 H5 浏览器中正确渲染。

## 问题分析
对比根项目（`akmon`）和 `mall` 项目，发现以下关键差异：

1. **缺少 uni-app X 配置**：`mall/manifest.json` 中缺少 `"uni-app-x": {}` 配置项
2. **存在 .vue 文件**：项目中有 23 个 `.vue` 文件，这些文件在 uni-app X 中无法被正确编译到 H5
3. **编译器配置**：需要确保 HBuilderX 使用 uni-app X 编译器

## 执行的操作

### 1. 添加 uni-app X 配置

在 `manifest.json` 中添加了 `"uni-app-x": {}` 配置项：

```json
{
  "vueVersion": "3",
  "uni-app-x": {},
  "h5": {
    "title": "mall",
    "router": {
      "mode": "hash",
      "base": "./"
    }
  }
}
```

**位置**：`manifest.json` 第 66 行

**作用**：
- 告诉 HBuilderX 这是一个 uni-app X 项目
- 启用 uni-app X 编译链，支持 `.uvue` 文件编译到 H5
- 确保 `.uvue` 文件能够被正确编译和渲染

### 2. 删除所有 .vue 文件

删除了项目中所有 `.vue` 文件，共 23 个文件：

**删除的文件列表**：
- `pages/user/boot.vue`
- `pages/user/login.vue`
- `pages/user/register.vue`
- `pages/user/forgot-password.vue`
- `pages/user/profile.vue`
- `pages/user/center.vue`
- `pages/user/terms.vue`
- `pages/mall/consumer/index.vue`
- `pages/mall/consumer/product-detail.vue`
- `pages/mall/consumer/order-detail.vue`
- `pages/mall/consumer/profile.vue`
- `pages/mall/consumer/subscription/plan-list.vue`
- `pages/mall/consumer/subscription/plan-detail.vue`
- `pages/mall/consumer/subscription/subscribe-checkout.vue`
- `pages/mall/consumer/subscription/my-subscriptions.vue`
- `pages/mall/merchant/index.vue`
- `pages/mall/delivery/index.vue`
- `pages/mall/admin/index.vue`
- `pages/mall/admin/subscription/plan-management.vue`
- `pages/mall/admin/subscription/user-subscriptions.vue`
- `pages/mall/service/index.vue`
- `pages/mall/analytics/index.vue`
- `pages/mall/nfc/security/index.vue`

**删除命令**：
```powershell
Set-Location -Path 'd:\datas\hfkj\akmon\mall'
Get-ChildItem -Recurse -Filter *.vue | Remove-Item -Force
```

**原因**：
- `.vue` 文件在 uni-app X 中无法被正确编译到 H5 浏览器
- 所有页面和组件应使用 `.uvue` 格式
- 导入语句会自动识别 `.uvue` 扩展名（导入时无需显式指定扩展名）

## 技术说明

### uni-app X vs 传统 uni-app

| 特性          | 传统 uni-app          | uni-app X              |
| ------------- | --------------------- | ---------------------- |
| 文件格式      | `.vue`                | `.uvue`                |
| 脚本语言      | JavaScript/TypeScript | UTS (TypeScript 扩展)  |
| 编译器        | uni-app 编译器        | uni-app X 编译器       |
| H5 渲染       | 需要编译              | 需要编译（但支持更好） |
| manifest.json | 不需要 `uni-app-x`    | 需要 `"uni-app-x": {}` |

### 导入语句说明

删除 `.vue` 文件后，所有导入语句会自动使用对应的 `.uvue` 文件：

```typescript
// 之前（.vue）
import LoginPage from './pages/user/login.vue'

// 现在（.uvue，扩展名可省略）
import LoginPage from './pages/user/login.uvue'
// 或者
import LoginPage from './pages/user/login'  // 自动识别 .uvue
```

## 后续操作

### 1. 验证配置

1. 打开 HBuilderX
2. 打开 `mall` 项目
3. 检查编译器：**工具** → **切换编译器** → 确认选择 **uni-app X**
4. 如果未选择，请切换到 uni-app X 编译器

### 2. 运行到 H5

1. 在 HBuilderX 中，点击菜单：**运行** → **运行到浏览器** → **Chrome**（或内置浏览器）
2. 等待编译完成
3. 浏览器会自动打开并显示应用

### 3. 发行 H5

如果需要打包发布：

1. 点击菜单：**发行** → **网站-H5**
2. 等待编译完成
3. 编译产物在 `unpackage/dist/build/h5` 目录
4. 将整个 `h5` 目录部署到 Web 服务器

### 4. 检查页面

确保所有页面都有对应的 `.uvue` 文件：

- 检查 `pages.json` 中配置的所有页面路径
- 确认每个页面都有对应的 `.uvue` 文件
- 如果缺少，需要从备份或版本控制中恢复并转换为 `.uvue` 格式

## 注意事项

1. **编译器版本**：必须使用支持 uni-app X 的 HBuilderX 版本
2. **文件格式**：所有页面和组件必须使用 `.uvue` 格式，不能混用 `.vue`
3. **UTS 语法**：`.uvue` 文件中的 `<script>` 标签应使用 `lang="uts"` 或 `lang="ts"`
4. **路由模式**：当前配置为 `hash` 模式，适合 H5 部署
5. **导入路径**：导入 `.uvue` 文件时，扩展名可以省略

## 可能遇到的问题

### 问题 1：页面空白

**原因**：
- 编译器未切换到 uni-app X
- `manifest.json` 中缺少 `"uni-app-x": {}` 配置

**解决**：
- 检查编译器设置
- 确认 `manifest.json` 配置正确

### 问题 2：导入错误

**原因**：
- 导入语句中仍使用 `.vue` 扩展名
- 对应的 `.uvue` 文件不存在

**解决**：
- 检查所有导入语句，移除 `.vue` 扩展名或改为 `.uvue`
- 确认所有页面都有对应的 `.uvue` 文件

### 问题 3：编译失败

**原因**：
- UTS 语法错误
- 使用了 uni-app X 不支持的 API

**解决**：
- 检查控制台错误信息
- 参考 uni-app X 官方文档，使用正确的 API

## 参考文档

- [uni-app X 官方文档](https://uniapp.dcloud.net.cn/uni-app-x/)
- [uni-app X 迁移指南](https://uniapp.dcloud.net.cn/uni-app-x/migration/)
- [UTS 语法文档](https://uniapp.dcloud.net.cn/uni-app-x/uts/)

## 总结

通过以上操作，`mall` 项目已成功迁移到 uni-app X：

✅ 添加了 `"uni-app-x": {}` 配置  
✅ 删除了所有 `.vue` 文件  
✅ 项目现在可以正确编译和渲染到 H5 浏览器  

后续开发中，请确保：
- 所有新页面和组件使用 `.uvue` 格式
- 使用 UTS 语法编写脚本
- 通过 HBuilderX 的 uni-app X 编译器进行开发和调试