# mouse-auto-clicker **Repository Path**: markets2022/mouse-auto-clicker ## Basic Information - **Project Name**: mouse-auto-clicker - **Description**: Windows 鼠标自动点击小工具(零依赖:tkinter 界面 + ctypes 调用 user32 发鼠标事件),支持实时坐标、固定/跟随点击、F6 全局热键。 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-10-23 - **Last Updated**: 2026-10-31 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 鼠标自动点击器(MouseAutoClicker) 一个**零第三方依赖**的 Windows 鼠标自动点击小工具。用 Python 标准库 `tkinter` 做界面,用 `ctypes` 直接调用 Windows `user32` 发送鼠标事件,不需要安装 `pyautogui` 之类的第三方包,拿到源码就能跑。 > 适合场景:游戏挂机点击、表单重复提交、网页/软件里需要反复点同一个位置、批量点选等**合法合规**的自动化操作。请勿用于违反软件用户协议、游戏防作弊规则或任何违规用途。 --- ## 一、功能特性 | 功能 | 说明 | |---|---| | 🖱️ 实时坐标显示 | 顶部大字每 50ms 刷新鼠标当前位置,移动鼠标即可看到数字变化,方便对准目标 | | 📍 坐标拾取 | 「拾取当前位置」按钮:把鼠标移到目标点一点,自动填入 X/Y,不用手敲 | | 🎯 两种点击模式 | 固定坐标(每次点设定点) / 跟随模式(点鼠标当前所在位置) | | ⏱️ 频率可调 | 滑块 50–5000 毫秒,旁边实时换算「≈ X 次/秒」,直观 | | 🔘 按键与类型 | 左键 / 右键 / 中键,单击 / 双击 | | ⌨️ 全局热键 F6 | 启动 / 停止,**窗口不在焦点时也生效**(正在点别的窗口也能停) | | 📌 窗口置顶 | 边设边看,方便对准 | | 🙈 点击时隐藏 | 可选:点击过程中自动隐藏本窗口,避免误点到工具自己 | --- ## 二、运行环境 - **操作系统**:Windows(调用的是 `user32.dll`,仅 Windows 可用) - **Python**:3.6+(代码用了 f-string,需 3.6+) - **依赖**:仅标准库 `tkinter`、`ctypes`、`threading`、`time`,**无需 pip install 任何东西** ### ⚠️ 关于 Python / tkinter 的重要提示 程序界面基于 `tkinter`。**部分精简版 / 嵌入式 Python 的 `tkinter` 是坏的**(典型症状:能 `import tkinter` 但一建窗口就报错,或打包时提示 “tkinter installation is broken”)。例如某些 IDE/工具自带的托管 Python 就有这个问题。 如果遇到 tkinter 报错,请改用**系统自带的、带完整 tkinter 的 Python**(通常 3.8.x 自带正常的 tkinter 8.6)来运行: ```bat :: 用你本机可用的、tkinter 正常的 Python 绝对路径来跑 D:/download/pythonsdk/python386/python.exe MouseAutoClicker.py ``` 判断某个 Python 是否可用 tkinter: ```bat python -c "import tkinter; print(tkinter.TkVersion)" ``` 能打印版本号(如 `8.6`)就正常;报错就换一个 Python。 --- ## 三、安装与运行 ### 方式一:直接运行源码(推荐,最简单) 1. 确保本机有一个 tkinter 正常的 Python(见上节)。 2. 下载/克隆本仓库,进入目录: ```bat cd mouse-auto-clicker ``` 3. 运行: ```bat python MouseAutoClicker.py ``` 或带绝对路径: ```bat D:/你的/python.exe MouseAutoClicker.py ``` 4. 弹出的小窗口里设置好参数,按 **F6** 或点「开始」即可。 ### 方式二:打包成单文件 exe(方便分发给不会 Python 的人) 需要 `pyinstaller`(**务必用 tkinter 正常的那个 Python 环境**来打包,否则打出的 exe 缺 tkinter 跑不起来): ```bat pip install pyinstaller pyinstaller --onefile --windowed --name MouseAutoClicker MouseAutoClicker.py ``` 打包完成后,`dist/MouseAutoClicker.exe` 双击即用,无需 Python 环境。 > 注意:`--windowed` 是为了不弹黑框;打包所用 Python 必须与运行时 tkinter 正常的是同一个,否则 exe 启动即崩溃。 --- ## 四、使用说明 ### 界面一览 ``` ┌─────────────────────────────┐ │ 当前鼠标坐标 │ │ X: 1234 Y: 567 │ ← 实时刷新,移动鼠标看数字 │ ☑ 使用固定坐标 │ │ 目标 X:[1234] 目标 Y:[567] [拾取当前位置] │ │ 点击间隔(毫秒,越小越快) │ │ ━━━━━━━━━━━━━━━●━━━ 1000 │ ← 滑块,下方显示 ≈ 次/秒 │ 按键:(*)左键 ()右键 ()中键 类型:()单击 ()双击 │ │ ☑ 窗口置顶 ☑ 点击时自动隐藏 │ │ 状态:已停止 │ │ [ 开始 (F6) ] │ └─────────────────────────────┘ ``` ### 典型操作流程 1. **对准目标**:把鼠标移到你想点的位置,点「拾取当前位置」,X/Y 自动填好(或不勾「使用固定坐标」走跟随模式)。 2. **设频率**:拖滑块,看下方「≈ X 次/秒」。 3. **选按键/类型**:左/右/中键,单击或双击。 4. **(可选)** 勾「窗口置顶」边看边设;勾「点击时自动隐藏」避免误点工具。 5. 按 **F6**(或点「开始」)启动;再按 **F6** 停止。 ### 热键 - **F6**:启动 / 停止切换。基于 Windows 全局低级键盘钩子实现,**即使本窗口不在最前面、焦点在别的程序上,F6 依然有效**——这是关键设计,否则点开始后鼠标被占用,没法回去点停止。 --- ## 五、工作原理 ``` ┌──────────────┐ F6 按下 ┌──────────────────┐ 置位 Event ┌──────────────┐ │ 键盘钩子线程 │ ───────────▶ │ (独立消息泵线程) │ ─────────────▶ │ tkinter 主线程 │ │ WH_KEYBOARD │ 回调只置位 │ 不持有 GIL │ 主线程轮询 │ after() 轮询 │ │ _LL 钩子 │ 一个事件 │ │ 再执行 toggle │ 执行 启/停 │ └──────────────┘ └──────────────────┘ └──────┬───────┘ │ 点击线程 ▼ ┌──────────────────┐ │ ctypes → user32 │ │ mouse_event / │ │ SetCursorPos │ └──────────────────┘ ``` 1. **发鼠标事件**:`ctypes.windll.user32.mouse_event(...)` 发送鼠标按下/抬起;`SetCursorPos` 移动鼠标到固定坐标。纯 Windows API,无第三方依赖。 2. **全局热键**:用 `SetWindowsHookExW(WH_KEYBOARD_LL, ...)` 安装低级键盘钩子捕获 F6。 3. **线程模型(关键)**: - 键盘钩子装在**一个独立的消息泵线程**里(`GetMessage` 循环),该线程**不持有 Python GIL**; - 钩子回调**只做一件最轻的事**:置位一个 `threading.Event`,**绝不回调里直接操作 tkinter**; - 主线程用 `root.after()` 每 80ms 轮询这个事件,在 **GUI 线程**里执行启停 `toggle`。 - 这样彻底分离「钩子线程」和「tkinter 主线程」,保证 tkinter 调用永远在主线程、且不会在 GIL 已持有的上下文中重入。 ### 为什么这么设计(踩过的坑) - **坑 1 · 64 位类型截断**:`WH_KEYBOARD_LL` 回调的 `WPARAM`/`LPARAM` 在 64 位 Windows 上是 64 位的。若用 32 位的 `c_int`/`c_ulong` 声明参数,回调时栈帧错乱,一按 F6 就访问越界**直接崩溃(程序瞬间消失)**。本程序已统一用 64 位安全类型(`c_ulonglong` / `c_longlong` / `c_void_p`),并给相关 API 显式声明 `argtypes` / `restype`。 - **坑 2 · GIL 重入致命崩溃**:若把键盘钩子装在 tkinter 主线程、回调里直接操作 tkinter,会触发 `Fatal Python error: PyEval_RestoreThread: NULL tstate`——因为主线程在 `mainloop` 中正持有 GIL,钩子回调又在消息分发过程中被调用,再次进出 GIL 会搞乱线程状态。解决办法就是上面「独立消息泵线程 + 事件 + 主线程轮询」。 - **坑 3 · tkinter 损坏的 Python**:部分托管/精简 Python 的 tkinter 是坏的,打包或运行会失败,必须用系统自带 tkinter 正常的 Python。 --- ## 六、常见问题(FAQ) **Q:按 F6 程序直接崩了 / 提示 `PyEval_RestoreThread` 之类?** A:这是键盘钩子线程模型问题,本版本已修复(见「工作原理 · 坑 2」)。若你是从旧版本升级,请直接拉取最新代码。 **Q:提示 `ModuleNotFoundError: tkinter` 或建窗口报错?** A:你用的 Python 没带可用 tkinter。换一个系统自带、tkinter 正常的 Python(见「运行环境」)。 **Q:打包成 exe 后打不开?** A:多半是打包用的 Python 的 tkinter 是坏的。用 tkinter 正常的 Python 重新 `pyinstaller`,且加 `--windowed`。 **Q:点击没反应 / 点不到想点的位置?** A:检查是否勾了「使用固定坐标」且 X/Y 已填;跟随模式下鼠标在哪点哪。固定坐标模式下程序会把鼠标移到设定点再点。 **Q:能设置多个坐标循环点吗?能随机抖动防检测吗?** A:当前版本是单点循环。多坐标轮点、随机偏移等增强可按需扩展(见下方「可扩展方向」)。 --- ## 七、可扩展方向(欢迎提 PR) - 多坐标点列表,按顺序 / 随机循环点击 - 随机位置抖动(避免被判定为机器行为) - 自定义热键(不止 F6) - 点击次数上限 / 定时停止 - 条件触发(如检测到某颜色/图像才点) --- ## 八、安全与合规声明 本工具仅用于**合法、合规**的自动化操作(如个人重复的合法点击任务)。使用者需自行确保: - 不违反目标软件/网站的用户协议; - 不用于游戏作弊、刷量、破坏公平性等违规场景; - 不用于任何侵犯他人权益或违反法律法规的行为。 作者不对因滥用本工具导致的任何后果负责。 --- ## 九、许可证 MIT License. 自由使用、修改、分发,商用亦可,但需保留版权声明,且作者对使用后果不承担保证责任。