game_service/gameSeriveUniapp
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
6bc1907d7a
gameSeriveUniapp/README-启动指南.md
ni ziyi 6bc1907d7a 小程序端初始化
2026-01-12 16:48:28 +08:00

6.8 KiB
Raw Blame History

游戏服务交易平台 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. 微信开发者工具会自动打开并加载项目

注意事项：

  • 需要先安装微信开发者工具
  • 在微信开发者工具中开启"服务端口"：设置 → 安全设置 → 服务端口 ✅

3. 运行到 H5（浏览器）

  1. 点击菜单：运行 → 运行到浏览器 → Chrome
  2. 或者工具栏选择"运行到浏览器 → Chrome"
  3. 会自动启动开发服务器并打开浏览器

方式二：使用命令行（适合熟悉命令行的开发者）

1. 安装依赖（如果没有安装）

cd game-service-miniapp-v2
npm install

2. 运行到微信小程序

npm run dev:mp-weixin

编译完成后：

  1. 打开微信开发者工具
  2. 导入项目：选择 game-service-miniapp-v2/unpackage/dist/dev/mp-weixin 目录
  3. AppID 选择"测试号"或输入你的小程序 AppID

3. 运行到 H5

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：页面空白或组件不显示

原因：组件库未正确引入

解决方案：

# 重新安装依赖
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 数据结构

我可以帮你创建这个文件，请告知是否需要。

📱 推荐的开发流程

开发微信小程序

# 1. 在 HBuilderX 中运行到微信开发者工具
运行 → 运行到小程序模拟器 → 微信开发者工具

# 2. 实时预览
修改代码后会自动编译并刷新

开发 H5 版本（快速调试）

# 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

  2. 微信开发者工具 - 小程序调试

  3. Node.js - 运行环境

可选工具

  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 配置

🎯 快速开始（完整步骤）

第一次启动项目

# 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

日常开发

# 直接在 HBuilderX 中点击运行即可
运行 → 运行到小程序模拟器 → 微信开发者工具

# 或者命令行
npm run dev:mp-weixin  # 微信小程序
npm run dev:h5         # H5

📞 遇到问题？

  1. 查看控制台错误信息：大部分问题会在控制台显示详细错误
  2. 查看 HBuilderX 控制台：运行 → 查看运行日志
  3. 检查微信开发者工具控制台：Console 和 Network 标签
  4. 清除缓存重试： 
    rm -rf unpackage
rm -rf node_modules
npm install
npm run dev:mp-weixin

最后更新: 2026-01-06