# 游戏服务交易平台 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