FunConnect/client/README.md

# FunConnect Client

Minecraft 联机桌面客户端，基于 Electron 构建，支持 **Windows / macOS / Linux** 全平台。

## 下载

从 [Releases](https://gt.funmc.cn/xiaobai/FunConnect/releases) 页面下载对应平台的安装包：

| 平台 | 文件 | 说明 |
|------|------|------|
| **Windows** | `FunConnect-x.x.x-Win-x64.exe` | 安装包（NSIS） |
| **Windows** | `FunConnect-x.x.x-Win-x64.exe` (portable) | 免安装版 |
| **macOS (Intel)** | `FunConnect-x.x.x-Mac-x64.dmg` | Intel Mac |
| **macOS (Apple Silicon)** | `FunConnect-x.x.x-Mac-arm64.dmg` | M1/M2/M3 Mac |
| **Linux** | `FunConnect-x.x.x-Linux-x64.AppImage` | 通用 Linux |
| **Linux** | `FunConnect-x.x.x-Linux-x64.deb` | Debian/Ubuntu |

## 功能

- **连接服务器** - 输入中继服务器地址一键连接
- **浏览房间** - 查看所有在线联机房间
- **创建房间** - 将本地 MC 服务器共享给好友
- **加入房间** - 输入房间号，自动建立本地代理
- **设置持久化** - 记住服务器地址、玩家名、端口等偏好
- **系统托盘** - 最小化到托盘，后台运行
- **自动重连** - 连接断开后自动尝试重新连接

## 从源码构建

### 前置要求

- Node.js 18+
- npm 9+
- Git

### 1. 安装依赖

```bash
cd client
npm install
```

> **国内镜像加速**（解决 Electron 下载慢）：
> ```bash
> # 设置镜像
> npm config set registry https://registry.npmmirror.com
>
> # Windows PowerShell
> $env:ELECTRON_MIRROR="https://npmmirror.com/mirrors/electron/"
> $env:ELECTRON_BUILDER_BINARIES_MIRROR="https://npmmirror.com/mirrors/electron-builder-binaries/"
> npm install
>
> # macOS / Linux
> ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/ \
> ELECTRON_BUILDER_BINARIES_MIRROR=https://npmmirror.com/mirrors/electron-builder-binaries/ \
> npm install
> ```

### 2. 开发模式

```bash
npm run dev
```

### 3. 编译打包

#### Windows（在 Windows 上执行）

```powershell
# 安装程序（NSIS）
npm run dist:win

# 输出:
#   release/FunConnect-x.x.x-Win-x64.exe        (安装包)
#   release/FunConnect-x.x.x-Win-x64.exe        (portable免安装)
```

#### macOS（在 macOS 上执行）

```bash
# DMG 安装包
npm run dist:mac

# 输出:
#   release/FunConnect-x.x.x-Mac-x64.dmg        (Intel)
#   release/FunConnect-x.x.x-Mac-arm64.dmg      (Apple Silicon)
```

#### Linux（在 Linux 上执行）

```bash
# AppImage + deb
npm run dist:linux

# 输出:
#   release/FunConnect-x.x.x-Linux-x64.AppImage
#   release/FunConnect-x.x.x-Linux-x64.deb
```

#### 全平台（需要对应平台环境）

```bash
npm run dist:all
```

> **注意**：跨平台编译限制——Windows 安装包需要在 Windows 上构建，macOS DMG 需要在 macOS 上构建。Linux AppImage 可在 Linux 或使用 Docker 构建。

### 4. CI/CD 自动构建（参考）

如果使用 GitHub Actions 或 GitLab CI，可以用 matrix 策略在多个平台上并行构建：

```yaml
# .gitlab-ci.yml 示例
build:
  stage: build
  parallel:
    matrix:
      - OS: [windows, macos, linux]
  script:
    - npm ci
    - npm run dist
  artifacts:
    paths:
      - client/release/
```

## 使用方法

### 房主（创建房间）

1. 启动客户端，输入中继服务器地址并连接
2. 进入「创建房间」页面
3. 填写房间名称、本地MC端口（默认25565）、游戏版本等信息
4. 点击「创建房间」，获得房间号
5. 将房间号分享给好友

### 玩家（加入房间）

1. 启动客户端，输入中继服务器地址并连接
2. 进入「加入房间」或在「房间列表」中点击加入
3. 输入房间号和中继服务器地址
4. 连接成功后，在 Minecraft 中添加服务器 `127.0.0.1:25566`
5. 开始联机！

## 项目结构

```
client/
├── build/                # 构建资源（图标等）
│   ├── icon.png          # 应用图标 (256x256)
│   └── icon.ico          # Windows 图标
├── src/main/
│   ├── index.ts          # Electron 主进程
│   ├── preload.ts        # 预加载脚本（IPC桥接）
│   ├── api-client.ts     # REST API 客户端
│   ├── relay-client.ts   # TCP 中继连接
│   └── local-proxy.ts    # 本地代理服务器
├── renderer/
│   ├── index.html        # 客户端界面
│   ├── style.css         # 样式
│   └── app.js            # 交互逻辑
├── package.json
└── tsconfig.json
```

## 设置说明

| 设置项 | 默认值 | 说明 |
|--------|--------|------|
| 玩家名称 | Player | 在房间中显示的名字 |
| 本地端口 | 25566 | MC连接的本地代理端口 |
| 自动重连 | 开启 | 连接断开后自动重连 |
| 最小化到托盘 | 开启 | 关闭窗口时隐藏到系统托盘 |

## 技术栈

- **Electron 28** - 跨平台桌面框架
- **TypeScript** - 主进程开发
- **electron-store** - 设置持久化
- **Axios** - HTTP 请求
- **electron-builder** - 全平台打包发布