199 lines
5.9 KiB
Markdown
199 lines
5.9 KiB
Markdown
# 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 编译器进行开发和调试
|