Appium 2 Java客户端连接失败常见原因及修复方案

Appium 2 升级后，Ja va 客户端常常会遭遇一个尴尬的报错：“could not connect to appium server”。很多人第一反应是去检查服务有没有启动、设备有没有连上，但往往绕了一大圈才发现，问题竟然出在最不起眼的地方。而今天我们就专门来聊一聊那个最容易被忽略、却又偏偏是最高发的问题——URL 末尾的斜杠。

在 Appium 2 和 Selenium 4 这变钱代化测试组合拳里，SessionNotCreatedException 这个异常看起来像在抱怨服务没响应或者设备识别出了问题。但真实的深水冲击波往往埋在一个极小、极不起眼的细节里：Appium Server 地址 URL 末尾到底有没有加那个“/”。

具体来说，下面这种写法，就会直接翻车：

return new IOSDriver(new URL("http://127.0.0.1:4723/"), options); // ❌ 错误：末尾含 '/'

为什么？因为 Selenium 4+ 和 Appium 2 的 HTTP 客户端（底层基于 OkHttp）对路径格式的处理比以前严格得多。一旦你的 URL 以斜杠结尾，客户端在拼接后续 API 路径（比如 /session）时，就很容易搞出 http://127.0.0.1:4723//session（看到了吗，双斜杠），Appium 服务端收到请求后匹配不到路由，然后默默地返回一个 404 Not Found。更“坑”的是，这个错误经常被包装成模糊的 SessionNotCreatedException，让你完全猜不到源头到底在哪。

✅ 正确的写法应该是这样的，一定去掉末尾的斜杠：

return new IOSDriver(new URL("http://127.0.0.1:4723"), options); // ✅ 正确：无尾部 '/'

同样的道理也适用于 AndroidDriver：

AndroidOptions options = new AndroidOptions()
    .setUdid("your-device-udid")
    .setPlatformName("Android")
    .setAutomationName("UiAutomator2")
    .setAppPackage("com.example.app")
    .setAppActivity(".MainActivity");

// 注意：URL 不带结尾斜杠
WebDriver driver = new AndroidDriver(new URL("http://127.0.0.1:4723"), options);

⚠️ 当然，光搞定斜杠还不够，Appium 2 的兼容性清单里，还有几项同样需要重点检查：

• 驱动类的变化一定要跟上：Appium 2 彻底废弃了旧式 RemoteWebDriver 直接传 DesiredCapabilities 的方式。必须使用类型化的 Options 类，比如 AndroidOptions 或 XCUITestOptions。同时要注意，引入的包路径必须是 io.appium.ja va_client.options 下的，别跟 org.openqa.selenium 的原生类搞混了。

• Ma ven 依赖的版本也要对齐：

  
      io.appium
      ja va-client
      8.6.0+ 
  
  
      org.seleniumhq.selenium
      selenium-ja va
      4.5.3+
  

• Server 启动参数的建议（特别是 macOS 加真机的组合）：

  appium --address 127.0.0.1 --port 4723 --allow-cors --base-path "/wd/hub"

  注：加上 --base-path "/wd/hub" 可以显式对齐 Selenium 的传统路径约定，虽然不是强制要求，但在排查问题时往往能多一份保障。

• 网络和权限的验证也别跳过：
  在终端敲一行 curl -v http://127.0.0.1:4723/status，如果返回 200 OK 并且带着 build.version 字段，那说明服务本身是可达的。要是超时或直接拒绝连接，那就得去 macOS 的防火墙里看看，有没有把 appium 进程给拦截了（路径在：系统设置 → 隐私与安全性 → 防火墙 → 防火墙选项 → 允许…）。

? 最终，建议你走一遍这套终极验证流程：

1. 先关掉所有 Appium 进程（pkill -f appium）；
2. 用上面推荐的命令重新启动服务；
3. 手动跑一次 curl 测试确认服务正常；
4. 去 Ja va 代码里把 URL 末尾的斜杠删掉；
5. 清理 Ma ven 缓存并重新编译（mvn clean compile）；
6. 运行单测，并盯着日志看有没有出现 Creating session with W3C capabilities——一旦看到这句话，就说明握手成功了。

说到底，Appium 2 的稳定性很大程度上取决于客户端与服务端之间的协议是否对齐。一个看似无害的斜杠，足够让你的自动化链路原地罢工。养成 URL 不带末尾斜杠的习惯、用强类型的 Options、定期检查依赖版本，这几件事做好，移动自动化的基础就算真正打牢了。