Virtual Gamepad Server

这是一个以 Python 为后端的网页虚拟手柄项目。

本项目仅支持 Windows 运行。

运行后，Windows 电脑会启动一个本地网页服务；手机或平板在同一局域网内打开网页，就可以把触摸操作发送到电脑端，电脑再通过 vgamepad 将这些操作映射成虚拟 Xbox 360 手柄输入。

项目结构

.
├─ python-backend/
│  ├─ app.py                 # Python 后端入口
│  ├─ requirements.txt       # Python 依赖
│  ├─ templates/index.html   # 页面模板
│  └─ static/                # 前端静态资源
├─ src/                      # Vite/React 前端源码
├─ package.json              # 前端开发依赖
└─ README.md

当前真正用于手柄联动的是 python-backend/ 这套后端服务和其中自带的网页资源。

src/、package.json 等文件属于前端源码/预览环境，不是日常使用这个项目所必需的启动方式。

需要注意：即使前端页面本身能在其他系统的浏览器里打开，完整项目依然只支持 Windows，因为虚拟手柄创建依赖 Windows 下的 vgamepad 和 ViGEmBus。

使用条件

在开始前，请先准备下面这些环境：

1. Windows 电脑 本项目仅支持 Windows，不支持 macOS 或 Linux。
2. Python 3 建议已正确加入系统环境变量。
3. ViGEmBus 驱动 这是生成虚拟 Xbox 360 手柄所必需的驱动。如果未安装，服务虽然可能能启动，但无法正常创建虚拟手柄。
4. 手机和电脑处于同一局域网 比如连接同一个 Wi-Fi。
5. 也可以使用内网穿透工具，如 Ngrok、Localtunnel 等，将服务端的端口映射到公网。

安装依赖

建议先进入后端目录，再创建虚拟环境并安装依赖：

cd python-backend
python -m venv .venv
.\.venv\Scripts\activate
pip install -r requirements.txt

requirements.txt 中当前使用到的主要依赖有：

• fastapi
• uvicorn
• python-socketio
• vgamepad
• jinja2

启动项目

在 python-backend 目录下执行：

python app.py

启动后，终端会输出类似下面的信息：

Connect from your phone via LAN: http://你的局域网IP:8000

这表示服务已经启动成功。

如何使用

1. 在电脑上启动后端服务。
2. 记下终端里显示的局域网地址，例如 http://192.168.1.10:8000。
3. 用手机浏览器访问这个地址。
4. 点击页面上的 Click to Start 按钮进入全屏手柄界面。
5. 使用页面上的摇杆、方向键、ABXY、肩键和扳机进行操作。
6. 电脑上的游戏或程序如果能识别 Xbox 360 手柄，就可以接收到这些输入。

页面功能说明

• 支持左右摇杆、方向键、ABXY、LB/RB、START/SELECT、LT/RT。
• 页面会通过 socket.io 实时把触摸输入发送给 Python 服务端。
• 设置面板支持调整控件位置、大小和部分灵敏度。
• 布局配置会保存在浏览器本地存储中。

常见问题

1. 手机打不开页面

请检查：

• 手机和电脑是否在同一局域网
• 访问的是否是终端输出的局域网地址，而不是 127.0.0.1
• Windows 防火墙是否拦截了 Python 或 8000 端口

2. 页面能打开，但电脑没有手柄输入

这通常表示虚拟手柄没有创建成功。请优先检查：

• 是否已安装 ViGEmBus 驱动
• 是否在 Windows 环境下运行
• 启动终端中是否出现创建手柄失败的提示

3. 关闭网页后手柄是否会释放

会。客户端断开连接后，服务端会释放对应的虚拟手柄实例。

前端源码说明

如果你只是“使用项目”，不需要处理根目录下的 Vite/React 开发环境。

如果你后续想继续改页面样式或交互，可以再使用根目录中的前端源码：

npm install
npm run dev

但这套前端开发环境更偏向界面预览/开发，不是当前项目的主要运行入口。