KeymouseGo安装教程：Windows/Linux/macOS全平台部署详解

2026-02-05 05:38:24作者：尤峻淳Whitney

1. 项目简介

KeymouseGo是一款类似按键精灵的自动化操作工具，支持鼠标键盘操作录制与回放，可在Windows、Linux和macOS系统上运行。本教程将详细介绍各平台的安装部署方法，包括二进制包安装和源码编译两种方式。

2. 环境准备

2.1 系统要求

操作系统	最低配置要求	依赖项
Windows	Windows 7+，64位系统	无特殊依赖
Linux	X11/Wayland桌面环境	libxdo-dev, python3-tk
macOS	macOS 10.14+	Xcode Command Line Tools

2.2 安装方式对比

安装方式	优点	缺点	适用人群
二进制包	无需配置环境，即下即用	版本可能不是最新	普通用户
源码编译	可获取最新特性	需要配置开发环境	开发者/高级用户

3. Windows平台安装

3.1 二进制包安装（推荐）

访问项目仓库：

git clone https://gitcode.com/gh_mirrors/ke/KeymouseGo

进入release页面下载最新Windows版本压缩包，解压后即可运行：
```
cd KeymouseGo
KeymouseGo.exe
```

3.2 源码编译安装

安装Python 3.10环境：
从Python官网下载并安装Python 3.10，勾选"Add Python to PATH"选项

安装依赖包：

# 克隆仓库
git clone https://gitcode.com/gh_mirrors/ke/KeymouseGo
cd KeymouseGo

# 安装Windows专用依赖
pip install -r requirements-windows.txt

# 安装打包工具
pip install pyinstaller

打包可执行文件：

pyinstaller -F -w --add-data "./assets;assets" KeymouseGo.py

运行程序：
```
cd dist
KeymouseGo.exe
```

4. Linux平台安装

4.1 二进制包安装

下载Linux版本压缩包并解压：

wget https://gitcode.com/gh_mirrors/ke/KeymouseGo/releases/download/vX.X.X/KeymouseGo-Linux.tar.gz
tar -zxvf KeymouseGo-Linux.tar.gz
cd KeymouseGo

添加执行权限并运行：
```
chmod +x KeymouseGo
./KeymouseGo
```

4.2 源码编译安装

安装系统依赖：

# Ubuntu/Debian
sudo apt update && sudo apt install -y python3 python3-pip python3-tk libxdo-dev

# Fedora/RHEL
sudo dnf install -y python3 python3-pip python3-tkinter libxdo-devel

安装Python依赖：

git clone https://gitcode.com/gh_mirrors/ke/KeymouseGo
cd KeymouseGo
pip3 install -r requirements-universal.txt
pip3 install pyinstaller

根据桌面环境打包：

# X11桌面环境
pyinstaller -F -w --add-data "./assets:assets" --hidden-import "pynput.keyboard._xorg" --hidden-import "pynput.mouse._xorg" KeymouseGo.py

# Wayland桌面环境
pyinstaller -F -w --add-data "./assets:assets" --hidden-import "pynput.keyboard._uinput" --hidden-import "pynput.mouse._uinput" KeymouseGo.py

运行程序：
```
cd dist
./KeymouseGo
```

5. macOS平台安装

5.1 二进制包安装

下载macOS版本压缩包：

git clone https://gitcode.com/gh_mirrors/ke/KeymouseGo
cd KeymouseGo

解压后授予执行权限：
```
chmod +x KeymouseGo
./KeymouseGo
```

5.2 源码编译安装

安装Xcode命令行工具：
```
xcode-select --install
```

安装Python环境：

# 使用Homebrew安装Python 3.10
brew install python@3.10

编译安装：

git clone https://gitcode.com/gh_mirrors/ke/KeymouseGo
cd KeymouseGo

# 安装依赖
pip3 install -r requirements-universal.txt
pip3 install pyinstaller

# 打包应用
pyinstaller -F -w --add-data "./assets:assets" --hidden-import "pynput.keyboard._darwin" --hidden-import "pynput.mouse._darwin" KeymouseGo.py

解决权限问题：

# 给予配置目录写权限
chmod -R 770 ~/.qt_material

# 在系统偏好设置中授予辅助功能权限

6. 常见问题解决

6.1 依赖安装问题

Windows系统

pip安装失败：

# 升级pip
python -m pip install --upgrade pip

# 使用国内镜像源
pip install -r requirements-windows.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

Linux系统

pynput依赖缺失：

# X11环境
sudo apt install -y libxtst-dev libx11-dev

# Wayland环境
sudo apt install -y libinput-dev

6.2 运行时错误

macOS系统

应用闪退：
前往"系统偏好设置 > 安全性与隐私 > 隐私 > 辅助功能"，添加终端和KeymouseGo应用

Linux系统

无法录制鼠标事件：

# 以root权限运行
sudo ./KeymouseGo

# 或添加用户到input组
sudo usermod -aG input $USER

7. 验证安装

成功安装后，运行程序会显示主界面，包含以下功能按钮：

录制：开始记录鼠标键盘操作
结束：停止录制
启动：回放已录制的操作
设置：配置回放速度、重复次数等参数

可通过录制一个简单的点击操作并回放来验证安装是否成功。

8. 卸载方法

8.1 二进制安装卸载

直接删除解压目录即可：

rm -rf KeymouseGo

8.2 源码安装卸载

# 删除项目目录
rm -rf KeymouseGo

# 卸载Python依赖（可选）
pip uninstall -r requirements-windows.txt -y  # Windows
pip3 uninstall -r requirements-universal.txt -y  # Linux/macOS