Appium连接失败：WinError 10061错误排查与解决方案

1. 项目概述：一个典型的Appium连接困局

如果你正在用Python写Appium自动化测试脚本，并且已经成功启动了Appium Server，但在脚本执行到driver = webdriver.Remote()这一行时，控制台突然抛出一个红色的错误信息：Failed to establish a new connection: [WinError 10061] 由于目标计算机积极拒绝，无法连接。，那么恭喜你，你遇到了Appium自动化测试入门路上一个非常经典，也足够让人抓狂的“拦路虎”。这个错误的核心，是你的Python客户端（脚本）尝试去和Appium Server建立网络连接，但Appium Server那边“大门紧闭”，直接拒绝了这次握手。对于新手来说，这个错误信息往往让人一头雾水，因为它指向了一个宽泛的网络问题，但根源却可能藏在环境配置、启动参数、端口占用等各个角落。

我处理过无数次类似的报错，从个人经验来看，WinError 10061在Appium语境下，几乎可以等价于“客户端找不到服务端”。这就像你按照地址去朋友家做客，但到了却发现要么门牌号不对，要么朋友根本没在家，要么他把门反锁了。解决这个问题的过程，就是一个系统性的“侦探”工作，需要你逐一排查地址（IP和端口）、主人状态（Appium Server进程）、以及敲门方式（Desired Capabilities配置）是否正确。本文将基于一个Python + Appium的典型测试场景，为你彻底拆解这个错误的成因，并提供一套从简到繁、步步为营的排查与解决方案。无论你是刚入门Appium自动化测试的新手，还是偶尔被此问题困扰的熟手，这份“排错指南”都能帮你快速定位问题，恢复测试流程。

2. 核心原理与错误根源深度解析

2.1 “积极拒绝”背后的网络通信模型

要理解WinError 10061，我们得先搞清楚Appium的工作模型。Appium遵循标准的客户端-服务器（Client-Server）架构：

• 服务器端 (Server)：即appium主进程。它启动后，会监听一个特定的网络端口（默认是4723），等待来自客户端的连接请求。你可以把它想象成一个提供“设备操控服务”的餐厅。
• 客户端 (Client)：即你的Python测试脚本，使用selenium库中的webdriver.Remote类。它的职责是向服务器发起连接，并发送一系列指令（即Desired Capabilities），告诉服务器：“我想在哪个设备上，打开哪个App，进行什么操作”。这就像顾客根据餐厅地址找上门并点餐。

Failed to establish a new connection: [WinError 10061] 由于目标计算机积极拒绝，无法连接。这个错误，发生在TCP/IP协议栈的“三次握手”阶段。当客户端向服务器指定的IP和端口发送SYN包（请求连接）时，如果服务器端根本没有程序在监听那个端口，操作系统内核会直接回一个RST包（重置连接），客户端收到后就会报告“连接被拒绝”。所谓“积极拒绝”，就是指目标端口有响应（回了RST），而不是网络不通（超时无响应）。所以，这个错误明确告诉我们：客户端找对地方了（IP可达），但那个“门”（端口）后面没有我们要找的“服务生”（Appium Server进程）。

2.2 导致“服务生不在岗”的五大常见原因

根据我的排查经验，导致Appium Server“不在岗”或“不认你”的原因，主要可以归结为以下五类，排查时也建议按此顺序进行：

1. Appium Server未启动或启动失败：这是最直接的原因。你根本没有运行appium命令，或者运行后因为环境问题（如Node.js版本、依赖缺失）导致进程异常退出。
2. 端口号不匹配：客户端代码里指定的端口号（如127.0.0.1:4723）与Appium Server实际监听的端口号不一致。你可能改了默认端口但代码没改，或者端口被其他程序占用了。
3. 主机地址（Host）错误：在非本地执行时（如脚本在机器A，Appium Server和设备在机器B），客户端代码中指定的主机IP地址不正确，无法路由到运行Appium Server的机器。
4. Appium Server启动参数限制：启动Appium Server时，使用了--address或--port参数，但参数设置与客户端连接意图不匹配。例如，--address 127.0.0.1会导致Server只接受来自本机的连接，如果客户端用局域网IP连接就会被拒绝。
5. 防火墙或安全软件拦截：系统防火墙、杀毒软件或公司网络策略阻止了本地回环地址（127.0.0.1）或特定端口（4723）的通信。这种情况在某些严格管控的企业环境中比较常见。

注意：很多人会混淆127.0.0.1和localhost。在绝大多数情况下，它们都指向本机。但在某些系统（如某些Windows配置了特定hosts文件或存在IPv6优先）下，localhost的解析可能会出问题。为了绝对可靠，在代码中直接使用127.0.0.1是更推荐的做法。

3. 系统性排查与解决方案实战

遇到10061错误，切忌盲目尝试。遵循一个系统的排查流程，可以帮你最高效地解决问题。下面我将按照从外到内、从简单到复杂的顺序，带你一步步操作。

3.1 第一步：基础检查——确认Appium Server状态

这是所有排查的起点。打开你的命令行终端（CMD, PowerShell, 或 Terminal）。

1. 检查Appium进程是否运行：

# 在Windows上，查找包含‘appium’的进程 tasklist | findstr appium # 在macOS/Linux上 ps aux | grep appium

如果没有任何输出，说明Appium Server根本没有启动。你需要去启动它。

2. 启动Appium Server并观察日志：不要直接双击桌面图标（如果有的话），而是通过命令行启动，这样你能看到所有输出日志，这对于诊断启动失败至关重要。

# 直接启动，使用默认设置（监听 0.0.0.0:4723） appium

启动成功后，你应该能看到类似以下的日志：

[Appium] Welcome to Appium v2.0.0 [Appium] Appium REST http interface listener started on 0.0.0.0:4723

关键信息：listener started on 0.0.0.0:4723。这表示Server正在0.0.0.0这个所有网络接口上监听4723端口，可以接受来自任何IP地址的连接。

如果启动失败，日志会打印错误信息。常见问题有：

• Node.js版本不兼容：Appium 2.x 需要 Node.js 16+。用node -v检查。
• 依赖驱动未安装：对于Android自动化，你需要安装appium-uiautomator2-driver；对于iOS，需要appium-xcuitest-driver。可以通过appium driver install uiautomator2来安装。
• Java环境问题：Android开发工具链（ADB）需要Java。确保JAVA_HOME环境变量已正确设置，且java -version可以执行。

3. 验证端口监听状态：即使appium命令启动了，也要确认它是否真的成功绑定了端口。

# Windows 使用 netstat netstat -ano | findstr :4723 # macOS/Linux 使用 lsof 或 netstat lsof -i :4723 # 或 netstat -an | grep 4723

如果端口4723被成功监听，你会看到一条记录，其中LISTENING状态表明正在监听。如果看不到，说明Appium Server可能启动后立即崩溃了，需要根据上一步的启动日志排查原因。

3.2 第二步：核对连接配置——客户端代码检查

确保你的Python脚本中的连接地址与Appium Server的实际监听地址完全匹配。这是最常出错的环节。

1. 检查Python连接代码：

from appium import webdriver from appium.options.common import AppiumOptions # 定义Desired Capabilities options = AppiumOptions() options.load_capabilities({ "platformName": "Android", "appium:platformVersion": "13", "appium:deviceName": "Android Emulator", "appium:app": "/path/to/your/app.apk", "appium:automationName": "UiAutomator2", "appium:noReset": True }) # ！！！重点关注这一行 ！！！ # 尝试连接Appium Server driver = webdriver.Remote('http://127.0.0.1:4723', options=options)

关键点分析：

• 协议：必须是http://。虽然Appium也支持HTTPS，但在本地测试中极少使用。
• 主机地址 (Host)：127.0.0.1代表本机。如果你的Appium Server运行在另一台电脑（如一个专门的测试机）上，这里需要替换成那台电脑的局域网IP地址，例如http://192.168.1.100:4723。
• 端口 (Port)：4723是Appium默认端口。如果你启动Appium时通过--port指定了其他端口（如appium --port 4724），这里必须同步修改。

2. 处理复杂的启动场景：

• 场景A：使用--address参数启动Appium

  appium --address 127.0.0.1 --port 4723

  这种启动方式，Appium Server只监听127.0.0.1这个回环地址。这意味着，只有从本机发起的连接（即Python脚本也在同一台机器）才能成功。如果你试图从另一台机器用局域网IP连接，会得到10061错误。解决方案：如果不需要远程连接，这样启动是安全的。如果需要远程连接，应使用--address 0.0.0.0或直接不加此参数（默认就是0.0.0.0）。

• 场景B：端口被占用如果默认的4723端口已被其他程序（可能是另一个Appium实例、或其他应用）占用，Appium Server会启动失败。你会看到类似Error: listen EADDRINUSE: address already in use :::4723的错误。解决方案：

  1. 关闭占用端口的进程（通过netstat -ano | findstr :4723找到PID，然后在任务管理器中结束）。
  2. 为Appium指定一个新端口启动：appium --port 4724，并相应修改Python代码中的连接地址为...:4724。

3.3 第三步：网络与系统环境深度排查

如果前两步都没问题，那么需要深入系统层面进行排查。

1. 防火墙与安全软件检查：尽管是本地回环通信（127.0.0.1），但某些过于“积极”的安全软件或Windows防火墙的某些规则可能会拦截。进行一个简单的测试：临时完全关闭Windows Defender防火墙（或你使用的第三方杀毒软件的网络防护功能），然后重试。如果问题解决，说明是防火墙的问题。你需要为Appium或Java（因为Appium Server是Node.js应用，但底层可能调用Java进程）添加防火墙入站规则，允许4723端口的TCP连接。

2. 使用curl或浏览器进行快速测试：在命令行中，使用curl工具可以直接测试Appium Server的HTTP接口是否可达，这比运行整个Python脚本更快捷。

curl http://127.0.0.1:4723/wd/hub/status

如果Appium Server正常运行且监听正确，你会收到一个JSON格式的响应，包含status: 0和一些版本信息。如果收到curl: (7) Failed to connect to 127.0.0.1 port 4723: Connection refused，那就直观地证实了10061错误，你需要回到第一步检查Server状态。

如果没有curl，也可以直接在浏览器地址栏输入http://127.0.0.1:4723/wd/hub/status。如果Server正常，浏览器会显示JSON数据；如果无法连接，浏览器会显示“无法访问此网站”之类的错误。

3. 检查主机文件 (Hosts File)：极少数情况下，系统的hosts文件（位于C:\Windows\System32\drivers\etc\hosts）被修改，将localhost或127.0.0.1指向了错误的地址。用记事本（以管理员身份运行）打开这个文件，确保没有异常的行将127.0.0.1重定向。通常，这个文件除了注释外应该是空的，或者只有一行127.0.0.1 localhost。

3.4 第四步：高级场景与疑难杂症处理

1. 使用Appium Desktop或Inspector：如果你同时在使用Appium Desktop（带图形界面的Appium）或Appium Inspector，需要注意它们可能会启动自己内置的Appium Server，并占用默认端口。确保你的Python脚本连接的是你意图中的那个Server实例。一个常见的冲突是：用命令行启动了Appium Server在4723端口，同时Appium Desktop也自动启动了一个Server在4723端口，导致端口冲突。建议：在调试阶段，关闭Appium Desktop，统一使用命令行管理Appium Server，以减少不确定性。

2. 公司代理或VPN影响：如果你身处公司网络，且系统设置了全局HTTP/HTTPS代理，或者连接了VPN，有时这些网络配置会干扰本地回环地址的通信。尝试暂时断开VPN，并在系统设置中关闭代理（“设置” -> “网络和Internet” -> “代理” -> 关闭“使用代理服务器”），然后重试。

3. Python环境与库版本冲突：虽然较少见，但陈旧的selenium或appium-python-client库可能与新版的Appium Server存在兼容性问题。确保你的库是最新的：

pip install --upgrade selenium appium-python-client

4. 一份可复现的完整工作流与示例代码

为了让你有一个清晰的参照，这里提供一个从零开始、确保能成功连接的最小化工作流和代码示例。

工作流步骤：

1. 环境准备：确保已安装Node.js (>=16)， Java JDK (8+)， Android SDK，并设置好ANDROID_HOME和JAVA_HOME环境变量。
2. 安装Appium：npm install -g appium。安装所需驱动：appium driver install uiautomator2。
3. 启动设备：启动Android模拟器（如通过Android Studio的AVD Manager）或连接真机，并通过adb devices命令确认设备已识别。
4. 启动Appium Server：打开一个命令行窗口，执行appium。保持这个窗口打开，观察日志。
5. 编写并执行Python脚本：在另一个命令行窗口或IDE中，运行下面的示例脚本。

示例Python脚本 (test_connection.py):

import time from appium import webdriver from appium.options.common import AppiumOptions from appium.webdriver.common.appiumby import AppiumBy def test_appium_connection(): """ 一个最小化的Appium连接测试脚本。 前提：已启动Appium Server (默认端口4723)，且有一个Android设备/模拟器可用。 """ # 1. 定义核心的Desired Capabilities # 这些参数告诉Appium你要在什么设备上测试什么应用 options = AppiumOptions() options.load_capabilities({ # 平台必须是 Android 或 iOS "platformName": "Android", # 设备系统版本，通过 `adb shell getprop ro.build.version.release` 获取 "appium:platformVersion": "13", # 设备名称，可以是任意字符串，但用于日志区分。真机可通过 `adb devices -l` 查看model "appium:deviceName": "Pixel_6_Pro_API_33", # 自动化引擎，Android通常用 UiAutomator2 "appium:automationName": "UiAutomator2", # 以下两项二选一： # A) 测试一个已安装的应用（通过包名） # "appium:appPackage": "com.android.calculator2", # "appium:appActivity": "com.android.calculator2.Calculator", # B) 安装并测试一个APK文件（提供绝对路径） # "appium:app": r"C:\Users\YourName\Downloads\your_app.apk", # 示例：使用Android自带的计算器 "appium:appPackage": "com.android.calculator2", "appium:appActivity": "com.android.calculator2.Calculator", # 可选：不重置应用数据（避免每次测试都清空数据） "appium:noReset": True, # 可选：设置命令超时时间（单位秒），防止因设备慢导致失败 "appium:newCommandTimeout": 60, }) # 2. 连接Appium Server # ！！！这是最关键的连接行，确保IP和端口与运行的Server一致 ！！！ server_url = 'http://127.0.0.1:4723' print(f"正在尝试连接Appium Server: {server_url}") try: # 初始化驱动，这会触发与Appium Server的HTTP连接 driver = webdriver.Remote(server_url, options=options) print("✅ 连接Appium Server成功！") # 3. 一个简单的操作示例：等待界面加载，然后点击一个数字 time.sleep(2) # 等待应用启动 # 假设点击数字5（根据实际计算器UI定位元素，这里仅为示例） # 实际定位需要借助Appium Inspector获取 # digit_5 = driver.find_element(AppiumBy.ID, "com.android.calculator2:id/digit_5") # digit_5.click() print("执行简单的界面操作...") # 这里可以添加你的测试逻辑 # 4. 测试完成后，等待几秒并退出 time.sleep(3) driver.quit() print("测试完成，驱动已退出。") except Exception as e: # 捕获连接或其他异常 print(f"❌ 连接或执行过程中发生错误：{type(e).__name__}") print(f"错误详情：{e}") # 特别处理连接拒绝错误 if "10061" in str(e) or "Connection refused" in str(e): print("\n>>>> 疑似WinError 10061问题，请按以下步骤排查：") print("1. 确认Appium Server是否已在另一个终端窗口启动 (`appium`)。") print("2. 确认Server启动日志中显示 'listener started on 0.0.0.0:4723'。") print("3. 在浏览器中访问 http://127.0.0.1:4723/wd/hub/status，看是否有JSON返回。") print("4. 检查Python代码中的 `server_url` 是否与Server监听的IP和端口一致。") print("5. 检查是否有防火墙或安全软件阻止了连接。") if __name__ == '__main__': test_appium_connection()

执行与验证：

1. 在一个终端运行appium。
2. 在另一个终端运行python test_connection.py。
3. 观察输出。如果看到“✅ 连接Appium Server成功！”，则大功告成。如果看到错误，脚本最后的异常处理部分会给出针对性的排查提示。

5. 常见问题排查速查表与避坑指南

即使按照上述流程，有时还是会遇到一些“诡异”的情况。下面这个表格总结了我遇到过的典型问题及解决方案，你可以像查字典一样快速对照。

独家避坑技巧：

1. 日志是你的最佳伙伴：永远不要忽略Appium Server启动和运行时的控制台日志。错误信息、警告和堆栈跟踪都直接指向问题根源。养成启动Server后先扫一眼日志是否有红色错误信息的习惯。
2. “最小化复现”原则：当遇到问题时，创建一个新的、最简单的测试脚本（就像上面的示例），只包含最基本的连接和打开应用操作。排除复杂业务逻辑的干扰，能更快定位是环境问题还是脚本问题。
3. 固定你的环境：在项目初期，就记录下所有关键组件的版本号（Node.js, Appium, Python库, 驱动版本，设备系统版本）。不同版本间可能存在兼容性问题。使用requirements.txt(Python) 和package.json(Node) 来管理依赖是个好习惯。
4. 善用appium-doctor：这是一个官方提供的环境诊断工具。运行appium-doctor可以检查你的Android和iOS环境配置是否完整，它会给出明确的修复建议。
5. 真机调试先授权：使用Android真机调试时，第一次连接电脑后，手机屏幕上会弹出“允许USB调试吗？”的授权对话框。务必点击“确定”，否则adb devices会显示设备为unauthorized，Appium也无法连接。

处理WinError 10061的过程，本质上是对Appium工作原理和网络基础的一次实践性理解。每一次成功的排查，都会让你对这套工具链的掌控更深一层。当你再看到这个错误时，不再会是困惑和沮丧，而是能冷静地打开终端，按照“服务状态 -> 连接配置 -> 系统环境”的路径，像侦探一样迅速找到那个被关上的“门”。