Ubuntu 22.04下pyautogui.locateOnScreen返回None如何解决

基础信息 #

• 运行环境：Ubuntu 22.04、Python 3.10.4
• 已装依赖：最新版pyautogui、opencv-python
• 问题现象：Chrome/Firefox打开WhatsApp网页版时，调用pt.locateOnScreen('clip_pic.png')始终返回None
• 问题代码：

import pyautogui as pt
import paperclip as pc
# from pynput.mouse import Controller, Button
from time import sleep

# mouse = Controller()

class WhatsApp:
    def __init__(self, speed=5, click_speed=.3):
        self.speed = speed
        self.click_speed = click_speed
        self.message = ''
        self.last_message = ''

    def nav_green_dot(self):
        try:
            # position = pt.locateOnScreen('clip_pic.png', confidence = .7)
            # position = pt.locateOnScreen('clip_pic.png')
            # print(position)
            print(pt.locateOnScreen('clip_pic.png'))
            
            # pt.moveTo(position[0:2], duration = self.speed)
            # pt.moveRel(-100, 0, duration = self.speed)
        except Exception as e:
            print ('Exception (nav_green_dot): ', e)

wa_bot = WhatsApp(speed = .5, click_speed = .4)
sleep(5)
wa_bot.nav_green_dot()

• 待匹配目标图标：
  

高频遗漏配置/操作点 #

按出现概率从高到低排序，逐一排查即可：

• Wayland显示协议不兼容
  Ubuntu 22.04默认启用Wayland显示服务，pyautogui的截图、坐标定位API在Wayland下存在严重兼容问题，多数场景下不会抛出显式报错，但会出现截图内容异常、坐标偏移、匹配失败的问题。修复方式：注销当前系统账号，在登录界面点击右下角齿轮图标，选择Ubuntu on Xorg选项后重新登录，切换到X11显示协议再运行代码。
• 缺少系统级依赖
  pyautogui在Ubuntu下的截图功能依赖scrot组件，缺少该组件时不会触发报错，但截图逻辑异常无法正常匹配。终端执行以下命令安装全部必需系统依赖：

  sudo apt update && sudo apt install -y scrot python3-tk python3-dev
  

• 显示缩放比例不匹配
  高分屏设备默认开启125%/150%/200%系统显示缩放时，pyautogui捕获的屏幕实际像素和你手动截取的模板图片像素尺寸不一致，直接导致匹配失败。先到「系统设置-显示」中将显示缩放调整为100%，注销重进后，重新截取目标图标保存为clip_pic.png再测试。
• 未开启置信度模糊匹配
  你当前代码注释掉了confidence参数，无参数调用locateOnScreen是严格像素匹配模式，浏览器抗锯齿渲染、不同浏览器的图标细微色差、系统主题差异都会导致严格匹配失败。将定位代码修改为带置信度的模糊匹配模式，可根据实际效果调整阈值（建议0.6-0.8区间，低于0.5容易出现误匹配）：

  position = pt.locateOnScreen('clip_pic.png', confidence=0.7)
  

• 模板图片格式/截取范围问题
  一是Ubuntu自带截图工具导出的图片可能带Alpha透明通道，和pyautogui截图的RGB色彩通道不匹配，可用GIMP打开模板图，选择「图像-模式-RGB」后重新导出覆盖原文件；二是模板图不要截取多余的周边区域，仅精准截取回形针图标本身即可，多余的空白、聊天框内容会大幅提升匹配失败概率。
• 窗口状态问题
  运行代码前确认WhatsApp网页所在浏览器窗口处于前台激活状态，目标图标完全显示在屏幕可视区域内，没有被其他窗口遮挡、也没有滚动到屏幕可视范围外。

内容的提问来源于stack exchange，提问作者IgorAlves