252 lines
6.8 KiB
Markdown
252 lines
6.8 KiB
Markdown
# 游戏服务交易平台 V2 - 启动指南
|
||
|
||
## 🚨 解决启动报错：GET http://localhost:3000/main.ts 404
|
||
|
||
**错误原因**：uni-app 项目不应该直接通过浏览器访问 `http://localhost:3000`，需要使用正确的运行方式。
|
||
|
||
---
|
||
|
||
## ✅ 正确的启动方式
|
||
|
||
### 方式一：使用 HBuilderX（推荐）
|
||
|
||
#### 1. 在 HBuilderX 中打开项目
|
||
1. 打开 HBuilderX
|
||
2. 文件 → 导入 → 从本地目录导入
|
||
3. 选择 `E:\workspace\web\game-service-miniapp-v2` 目录
|
||
|
||
#### 2. 运行到微信开发者工具
|
||
1. 在 HBuilderX 中，点击菜单：**运行 → 运行到小程序模拟器 → 微信开发者工具**
|
||
2. 或者直接点击工具栏的运行按钮，选择"运行到微信开发者工具"
|
||
3. 首次运行会自动编译，生成到 `unpackage/dist/dev/mp-weixin` 目录
|
||
4. 微信开发者工具会自动打开并加载项目
|
||
|
||
**注意事项**：
|
||
- 需要先安装[微信开发者工具](https://developers.weixin.qq.com/miniprogram/dev/devtools/download.html)
|
||
- 在微信开发者工具中开启"服务端口"：设置 → 安全设置 → 服务端口 ✅
|
||
|
||
#### 3. 运行到 H5（浏览器）
|
||
1. 点击菜单：**运行 → 运行到浏览器 → Chrome**
|
||
2. 或者工具栏选择"运行到浏览器 → Chrome"
|
||
3. 会自动启动开发服务器并打开浏览器
|
||
|
||
---
|
||
|
||
### 方式二：使用命令行（适合熟悉命令行的开发者）
|
||
|
||
#### 1. 安装依赖（如果没有安装）
|
||
```bash
|
||
cd game-service-miniapp-v2
|
||
npm install
|
||
```
|
||
|
||
#### 2. 运行到微信小程序
|
||
```bash
|
||
npm run dev:mp-weixin
|
||
```
|
||
|
||
编译完成后：
|
||
1. 打开微信开发者工具
|
||
2. 导入项目：选择 `game-service-miniapp-v2/unpackage/dist/dev/mp-weixin` 目录
|
||
3. AppID 选择"测试号"或输入你的小程序 AppID
|
||
|
||
#### 3. 运行到 H5
|
||
```bash
|
||
npm run dev:h5
|
||
```
|
||
|
||
然后在浏览器访问：`http://localhost:5173`（端口可能不同，查看终端输出）
|
||
|
||
---
|
||
|
||
## 🔧 常见问题解决
|
||
|
||
### 问题1：HBuilderX 运行报错"未找到微信开发者工具"
|
||
|
||
**解决方案**：
|
||
1. 确保已安装微信开发者工具
|
||
2. 在 HBuilderX 中配置路径：
|
||
- 工具 → 设置 → 运行配置 → 微信开发者工具路径
|
||
- Windows 默认路径：`C:\Program Files (x86)\Tencent\微信web开发者工具\cli.bat`
|
||
- Mac 默认路径：`/Applications/wechatwebdevtools.app/Contents/MacOS/cli`
|
||
|
||
### 问题2：微信开发者工具打开失败
|
||
|
||
**解决方案**：
|
||
1. 在微信开发者工具中开启"服务端口"
|
||
2. 设置 → 安全设置 → 服务端口 ✅
|
||
3. 重启微信开发者工具和 HBuilderX
|
||
|
||
### 问题3：页面空白或组件不显示
|
||
|
||
**原因**：组件库未正确引入
|
||
|
||
**解决方案**：
|
||
```bash
|
||
# 重新安装依赖
|
||
cd game-service-miniapp-v2
|
||
rm -rf node_modules
|
||
npm install
|
||
```
|
||
|
||
### 问题4：TypeScript 报错
|
||
|
||
**解决方案**：
|
||
1. 确保安装了 TypeScript 相关依赖
|
||
2. 检查 `tsconfig.json` 配置是否正确
|
||
3. 在 HBuilderX 中：工具 → 设置 → 插件配置 → TypeScript → 开启
|
||
|
||
### 问题5：Mock 数据相关报错
|
||
|
||
**当前状态**：项目使用 Mock 数据，但 `src/mock` 目录可能缺失
|
||
|
||
**临时解决方案**：
|
||
1. 创建 `src/mock/index.ts` 文件
|
||
2. 创建基础 Mock 数据结构
|
||
|
||
我可以帮你创建这个文件，请告知是否需要。
|
||
|
||
---
|
||
|
||
## 📱 推荐的开发流程
|
||
|
||
### 开发微信小程序
|
||
```bash
|
||
# 1. 在 HBuilderX 中运行到微信开发者工具
|
||
运行 → 运行到小程序模拟器 → 微信开发者工具
|
||
|
||
# 2. 实时预览
|
||
修改代码后会自动编译并刷新
|
||
```
|
||
|
||
### 开发 H5 版本（快速调试）
|
||
```bash
|
||
# 1. 命令行运行
|
||
npm run dev:h5
|
||
|
||
# 2. 浏览器访问
|
||
http://localhost:5173
|
||
|
||
# 3. 使用浏览器开发者工具调试
|
||
F12 → Console/Network/Elements
|
||
```
|
||
|
||
### 角色切换调试
|
||
项目支持三种角色（用户、商家、代练），可以在登录后切换：
|
||
|
||
1. 首次登录会进入用户端
|
||
2. 点击个人中心 → 角色切换
|
||
3. 选择商家或代练角色查看对应页面
|
||
|
||
**Mock 数据默认角色**：
|
||
- 用户（customer）
|
||
- 商家（merchant）
|
||
- 代练（player）
|
||
|
||
---
|
||
|
||
## 🛠️ 开发工具推荐
|
||
|
||
### 必需工具
|
||
1. **HBuilderX** - uni-app 官方 IDE
|
||
- 下载：https://www.dcloud.io/hbuilderx.html
|
||
- 推荐版本：最新正式版
|
||
|
||
2. **微信开发者工具** - 小程序调试
|
||
- 下载：https://developers.weixin.qq.com/miniprogram/dev/devtools/download.html
|
||
- 记得开启"服务端口"
|
||
|
||
3. **Node.js** - 运行环境
|
||
- 下载：https://nodejs.org/
|
||
- 推荐版本：16.x 或 18.x（LTS）
|
||
|
||
### 可选工具
|
||
1. **VS Code** - 代码编辑（如果不喜欢 HBuilderX）
|
||
- 需要安装插件：Volar, uni-app snippets
|
||
|
||
2. **微信开发者工具** - 真机调试
|
||
- 可以扫码在真机上预览
|
||
|
||
---
|
||
|
||
## 📦 项目目录说明
|
||
|
||
```
|
||
game-service-miniapp-v2/
|
||
├── src/ # 源代码目录
|
||
│ ├── pages/ # 公共页面（登录、个人中心等）
|
||
│ ├── pages-user/ # 用户端分包
|
||
│ ├── pages-merchant/ # 商家端分包
|
||
│ ├── pages-player/ # 代练端分包
|
||
│ ├── components/ # 公共组件
|
||
│ ├── store/ # Pinia 状态管理
|
||
│ ├── types/ # TypeScript 类型定义
|
||
│ ├── utils/ # 工具函数
|
||
│ ├── static/ # 静态资源
|
||
│ ├── App.vue # 应用入口
|
||
│ ├── main.ts # 主入口文件
|
||
│ ├── pages.json # 页面配置
|
||
│ └── manifest.json # 应用配置
|
||
├── unpackage/ # 编译输出目录
|
||
├── node_modules/ # 依赖包
|
||
├── package.json # 项目配置
|
||
├── vite.config.ts # Vite 配置
|
||
└── tsconfig.json # TypeScript 配置
|
||
```
|
||
|
||
---
|
||
|
||
## 🎯 快速开始（完整步骤）
|
||
|
||
### 第一次启动项目
|
||
|
||
```bash
|
||
# 1. 进入项目目录
|
||
cd E:\workspace\web\game-service-miniapp-v2
|
||
|
||
# 2. 安装依赖（如果还没有安装）
|
||
npm install
|
||
|
||
# 3. 运行到微信小程序（推荐）
|
||
# 方式A：使用 HBuilderX
|
||
打开 HBuilderX → 导入项目 → 运行到微信开发者工具
|
||
|
||
# 方式B：使用命令行
|
||
npm run dev:mp-weixin
|
||
# 然后在微信开发者工具中导入 unpackage/dist/dev/mp-weixin
|
||
|
||
# 4. 或者运行到 H5（快速调试）
|
||
npm run dev:h5
|
||
# 浏览器访问 http://localhost:5173
|
||
```
|
||
|
||
### 日常开发
|
||
|
||
```bash
|
||
# 直接在 HBuilderX 中点击运行即可
|
||
运行 → 运行到小程序模拟器 → 微信开发者工具
|
||
|
||
# 或者命令行
|
||
npm run dev:mp-weixin # 微信小程序
|
||
npm run dev:h5 # H5
|
||
```
|
||
|
||
---
|
||
|
||
## 📞 遇到问题？
|
||
|
||
1. **查看控制台错误信息**：大部分问题会在控制台显示详细错误
|
||
2. **查看 HBuilderX 控制台**：运行 → 查看运行日志
|
||
3. **检查微信开发者工具控制台**：Console 和 Network 标签
|
||
4. **清除缓存重试**：
|
||
```bash
|
||
rm -rf unpackage
|
||
rm -rf node_modules
|
||
npm install
|
||
npm run dev:mp-weixin
|
||
```
|
||
|
||
---
|
||
|
||
**最后更新**: 2026-01-06
|