# Tap小游戏插件 - 环境检查说明

## 🎯 核心机制

本插件采用**构建前检查 + 双重保障**机制，确保在任何环境下都能顺利完成转换。

## 🔍 构建前环境检查

### 检查时机
在点击"构建"按钮后，**微信小游戏构建开始前**，插件会自动进行环境检查。

### 检查内容
1. **Node.js版本**：检查是否 >= 12.0
2. **转换器配置**：检查插件文件完整性
3. **Python环境**：检查是否有Python作为保底方案

### 检查结果

#### ✅ 情况1：环境完美（最常见）
```
✓ Node.js 14.17.0 兼容
✓ 转换器配置文件完整
→ 直接开始构建
```

#### ⚠️ 情况2：Node.js版本低 + 有Python
```
❌ Node.js 10.x 版本过低
✓ 检测到 Python 3.9
→ 弹窗提示："将使用Python脚本进行转换"
→ 继续构建
```

#### ❌ 情况3：Node.js版本低 + 无Python
```
❌ Node.js 10.x 版本过低
❌ 未检测到Python
→ 弹窗提示："需要升级Cocos Creator或安装Python"
→ 阻止构建
```

## 🛡️ 双重保障机制

### 转换流程

```
微信小游戏构建完成
        ↓
┌───────────────────┐
│ 1. TypeScript转换器│
│   （优先使用）     │
└───────┬───────────┘
        │
    ✓ 成功？
        │
        ├─── 是 ──→ ✅ 转换完成
        │
        └─── 否 ──→ ┌───────────────────┐
                   │ 2. Python保底方案  │
                   │   （自动切换）     │
                   └───────┬───────────┘
                           │
                       ✓ 成功？
                           │
                           ├─── 是 ──→ ✅ 转换完成（弹窗提示）
                           │
                           └─── 否 ──→ ❌ 转换失败（显示详细错误）
```

### 优先级说明

1. **TypeScript转换器**（默认，性能最好）
   - 完全自动化
   - 无需外部依赖
   - 速度最快

2. **Python脚本**（保底方案）
   - 需要用户安装Python 3.6+
   - 兼容性最强
   - 可以在任何环境运行

## 📋 用户操作指南

### 场景1：环境检查失败，无法构建

**弹窗提示**：
```
Node.js版本过低（v10.x），需要12.0或更高版本

请升级Cocos Creator到3.8.0或更高版本
备选方案：安装Python 3.6+作为保底转换工具
```

**解决方案（二选一）**：

**方案A：升级Cocos Creator（推荐）**
1. 下载最新版本的Cocos Creator
2. 重新安装
3. 重新导入项目

**方案B：安装Python（保底方案）**
1. Windows：
   - 下载Python 3.6+：https://www.python.org/downloads/
   - 安装时勾选"Add Python to PATH"

2. macOS：
   ```bash
   brew install python3
   ```

3. Linux：
   ```bash
   sudo apt-get install python3
   ```

4. 验证安装：
   ```bash
   python3 --version
   # 应该显示：Python 3.x.x
   ```

### 场景2：TypeScript转换失败，自动使用Python

**弹窗提示**：
```
TypeScript转换器失败，已自动使用Python保底方案完成转换

建议升级Cocos Creator以获得更好的性能
```

**说明**：
- 转换已经成功完成
- game.zip已生成
- 可以正常上传到TapTap平台
- 建议升级Cocos Creator获得更好性能

**可选操作**：
- 如果经常遇到这个提示，建议升级Cocos Creator
- 或者继续使用Python方案（虽然慢一点但更稳定）

### 场景3：两种方案都失败

**弹窗提示**：
```
转换失败，请查看控制台日志获取详细信息

TypeScript转换器错误：[错误信息1]
Python保底方案错误：[错误信息2]
```

**排查步骤**：
1. 打开Cocos Creator控制台
2. 查看详细的错误日志
3. 截图发送给技术支持

## 🔧 常见问题

### Q1: 为什么要构建前检查？
**A**: 避免浪费时间。微信小游戏构建可能需要几分钟，如果环境不满足，等构建完再失败会很浪费时间。

### Q2: Python保底方案会不会很慢？
**A**: 比TypeScript方案慢一些（大约慢20-30%），但更稳定，兼容性更强。

### Q3: 我可以强制使用Python方案吗？
**A**: 目前插件会自动选择最优方案。如果经常需要使用Python，建议直接运行converter目录下的wx_converter.py脚本。

### Q4: 环境检查可以跳过吗？
**A**: 不建议。环境检查只需要几秒钟，可以避免构建失败的问题。

### Q5: 我升级了Cocos Creator，还会用Python吗？
**A**: 不会。升级后Node.js版本满足要求，会优先使用TypeScript转换器。

## 📞 技术支持

如果遇到问题：
1. 查看控制台完整日志
2. 记录弹窗提示内容
3. 提供以下信息：
   - Cocos Creator版本
   - 操作系统版本
   - Node.js版本（运行 `node --version`）
   - Python版本（运行 `python3 --version`）
   - 完整的错误日志

## ✅ 推荐配置

### 最佳配置（推荐）
- Cocos Creator: 3.8.8 或更高
- 无需额外安装任何工具
- 完全自动化

### 保险配置
- Cocos Creator: 任意版本
- Python: 3.6 或更高
- 可以在任何环境工作
