Appium 2.0 Java客户端默认尝试在项目根目录下查找 appium/build/lib/main.js，导致 InvalidServerInstanceException；正确做法是显式指定 Appium CLI 的实际安装路径（即 appium.js 所在位置），而非依赖自动探测。
appium 2.0 java客户端默认尝试在项目根目录下查找 `appium/build/lib/main.js`，导致 `invalidserverinstanceexception`；正确做法是显式指定 appium cli 的实际安装路径（即 `appium.js` 所在位置），而非依赖自动探测。
在 Appium 2.0 中，Java 客户端（io.appium:java-client）已不再自动定位全局安装的 Appium CLI 入口文件（appium.js），而是默认回退到相对路径 ./appium/build/lib/main.js —— 这通常仅存在于从源码构建的开发环境，而非 npm 全局安装的生产环境。因此，当你通过 npm install -g appium 安装后，new AndroidDriver(capabilities) 内部调用 AppiumDriverLocalService.buildDefaultService() 时，会因找不到该路径而抛出异常：
io.appium.java_client.service.local.InvalidServerInstanceException: The main Appium script does not exist at '/<project path>/appium/build/lib/main.js'</project>
✅ 根本解决方案：显式配置 appium.js 的绝对路径
你需要手动构建 AppiumDriverLocalService 实例，并通过 .withAppiumJS(File(...)) 明确传入 appium.js 的真实路径。该文件通常位于：
- macOS / Linux：
$(npm root -g)/appium/build/lib/main.js - Windows：
%APPDATA%\npm\node_modules\appium\build\lib\main.js
（注意：Appium ≥ 2.0 的主入口为build/lib/main.js，而非旧版的lib/main.js）
? Java 示例代码（推荐写法）：
import io.appium.java_client.service.local.AppiumDriverLocalService;
import io.appium.java_client.service.local.AppiumServiceBuilder;
import org.openqa.selenium.remote.DesiredCapabilities;
private AppiumDriver createAndroidDriver(int deviceIndex) {
DesiredCapabilities capabilities = this.capabilitiesFactory.createCapabilities(this.currentTestPlatform);
// ✅ 关键：显式指定 appium.js 绝对路径
String appiumJsPath = System.getProperty("user.home") + "/.nvm/versions/node/v18.17.0/lib/node_modules/appium/build/lib/main.js";
// ⚠️ 替换为你的实际路径！可用 `npm list -g appium --depth=0` 查看安装位置
AppiumDriverLocalService service = new AppiumServiceBuilder()
.usingAnyFreePort()
.withAppiumJS(new File(appiumJsPath))
.build();
service.start(); // 必须显式启动
return new AndroidDriver(service, capabilities);
}
? 辅助技巧：动态获取路径（跨平台兼容）
若使用 Node.js 环境管理器（如 nvm、nvm-windows 或 Volta），建议通过脚本或配置项注入路径。例如，在 Maven/Gradle 中可通过系统属性传入：
mvn test -Dappium.js.path="/usr/local/lib/node_modules/appium/build/lib/main.js"
然后 Java 中读取：
String appiumJsPath = System.getProperty("appium.js.path");
if (appiumJsPath == null) {
throw new IllegalStateException("Please set system property 'appium.js.path'");
}
⚠️ 重要注意事项：
- 不要依赖
AppiumDriverLocalService.buildDefaultService()—— 它在 Appium 2.0+ 中已失效； -
usingDriverExecutable(File)是用于指定node可执行文件路径（非 Appium），仅当自定义 Node 版本时才需设置； - 启动服务后务必调用
service.stop()在测试结束时释放端口，避免端口占用； - 若使用 Appium Desktop，请勿混用 CLI 和 GUI 服务——确保
appium-js-path指向 CLI 版本。
总结：Appium 2.0 的 Java 客户端要求「显式路径优先」，这是为增强环境可控性所做的必要设计变更。只需一步——正确配置 withAppiumJS(...)，即可彻底规避路径探测失败问题。
