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

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 二进制包安装（推荐）

1. 访问项目仓库：

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

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

   cd KeymouseGo
   KeymouseGo.exe
   

3.2 源码编译安装

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

2. 安装依赖包：

   # 克隆仓库
   git clone https://gitcode.com/gh_mirrors/ke/KeymouseGo
   cd KeymouseGo
   
   # 安装Windows专用依赖
   pip install -r requirements-windows.txt
   
   # 安装打包工具
   pip install pyinstaller
   

3. 打包可执行文件：

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

4. 运行程序：

   cd dist
   KeymouseGo.exe
   

4. Linux平台安装

4.1 二进制包安装

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
   

2. 添加执行权限并运行：

   chmod +x KeymouseGo
   ./KeymouseGo
   

4.2 源码编译安装

1. 安装系统依赖：

   # 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
   

2. 安装Python依赖：

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

3. 根据桌面环境打包：

   # 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
   

4. 运行程序：

   cd dist
   ./KeymouseGo
   

5. macOS平台安装

5.1 二进制包安装

1. 下载macOS版本压缩包：

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

2. 解压后授予执行权限：

   chmod +x KeymouseGo
   ./KeymouseGo
   

5.2 源码编译安装

1. 安装Xcode命令行工具：

   xcode-select --install
   

2. 安装Python环境：

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

3. 编译安装：

   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
   

4. 解决权限问题：

   # 给予配置目录写权限
   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

9. 总结

本教程详细介绍了KeymouseGo在三大操作系统上的安装方法，用户可根据自身需求选择合适的安装方式。对于普通用户，推荐使用二进制包安装以获得最佳体验；开发者可通过源码编译获取最新特性。如遇到安装问题，可参考常见问题解决章节或访问项目issue页面寻求帮助。

10. 扩展阅读

• KeymouseGo使用指南
• 脚本语法说明
• 自动化任务案例集合