在Next.js应用中使用appium-adb构建遇UnhandledSchemeError如何解决？

问题根源 #

appium-adb是专为Node.js环境设计的工具库，依赖child_process这类Node.js核心模块（此处使用了node:协议的导入方式）。而Next.js的客户端构建流程默认不支持Node.js专属模块和node:协议——因为客户端代码要运行在浏览器中，不存在这些Node环境特有的API。

解决方案 #

1. 限定appium-adb的使用场景

appium-adb仅能在Node.js环境运行，所以你只能在Next.js的服务端代码中使用它，包括：

• API路由（app/api/或pages/api/下的文件）
• Server Components（Next.js 13+ App Router默认的服务端组件）
• 服务端数据获取方法（如getServerSideProps、getStaticProps）

2. 配置Webpack支持node:协议

如果在服务端代码中使用仍报错，修改next.config.js，让Webpack处理node:协议：

/** @type {import('next').NextConfig} */
const nextConfig = {
  webpack: (config, { isServer }) => {
    // 仅在服务端打包时处理node:协议
    if (isServer) {
      config.resolve.plugins = config.resolve.plugins || [];
      config.resolve.plugins.push({
        apply(resolver) {
          resolver.hooks.resolve.tap('NodeProtocolResolver', (request) => {
            if (request.request.startsWith('node:')) {
              return {
                request: request.request.slice(5), // 移除node:前缀
                path: request.path,
                relativePath: request.relativePath,
              };
            }
          });
        },
      });
    }
    return config;
  },
};

module.exports = nextConfig;

也可以用别名映射的方式简化配置：

const nextConfig = {
  webpack: (config, { isServer }) => {
    if (isServer) {
      config.resolve.alias = {
        ...config.resolve.alias,
        'node:child_process': 'child_process',
        // 若有其他node:前缀的模块，可在此添加映射
      };
    }
    return config;
  },
};

module.exports = nextConfig;

3. 移除客户端代码中的appium-adb引入

如果误在客户端组件（标注'use client'的组件）中引入了appium-adb，直接删除该引入即可——浏览器环境无法运行依赖Node.js核心模块的库，appium-adb操作ADB设备的功能也不可能在浏览器中实现。

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