docmirror/dev-sidecar · error

未找到可用的 macOS 网络服务，无法设置系统代理

Error message

未找到可用的 macOS 网络服务，无法设置系统代理

What it means

When setting the macOS system proxy, getMacNetworkService must determine which network service (e.g. Wi-Fi, Ethernet) to configure. It tries route-based detection (`route -n get 0.0.0.0` → device → networksetup -listnetworkserviceorder) and a fallback scan of `networksetup -listallnetworkservices`; if both fail to yield a service it throws this error instead of writing proxy settings to an unknown interface.

Source

Thrown at packages/core/src/shell/scripts/set-system-proxy/index.js:277

      log.warn('macOS 代理服务检测：未检测到当前网络设备，尝试备用方法')
    }
  } catch (e) {
    log.warn('macOS 代理服务检测：获取路由信息失败:', e.message, '，尝试备用方法')
  }

  try {
    const allServicesOutput = await exec('networksetup -listallnetworkservices')
    const fallbackService = pickMacNetworkService(allServicesOutput)
    if (fallbackService) {
      log.info('macOS 代理服务检测：通过服务列表备用方法找到网络服务:', fallbackService)
      return fallbackService
    }
    log.warn('macOS 代理服务检测：未通过服务列表找到可用网络服务')
  } catch (e) {
    log.warn('macOS 代理服务检测：获取所有网络服务列表失败:', e.message)
  }

  throw new Error('未找到可用的 macOS 网络服务，无法设置系统代理')
}

// macOS exit code 14 = "You don't have permission to change the system preferences."
const MACOS_NETWORKSETUP_PERMISSION_ERROR_CODE = 14

/**
 * POSIX single-quote escaping: wraps `arg` in single quotes, escaping any
 * embedded single quotes with the '\''-idiom.  This prevents shell
 * metacharacter expansion regardless of the character set of the value.
 * @param {string|number} arg
 * @returns {string}
 */
function shellEscapeArg (arg) {
  return "'" + String(arg).replace(/'/g, "'\\''") + "'"
}

/**
 * Strict-validate a proxy host (IPv4 / IPv6 / hostname) and throw if the

View on GitHub (pinned to 7710cd56cc)

Solutions

1. Enable/connect a real network interface (turn Wi-Fi on or plug Ethernet) so a default route and service exist, then retry.
2. Verify manually: `route -n get 0.0.0.0` shows a device, and `networksetup -listallnetworkservices` lists an enabled service.
3. If a VPN (utun) owns the default route, disconnect it or set the proxy on the underlying Wi-Fi/Ethernet service manually via System Settings.
4. Check the core.log lines starting with 'macOS 代理服务检测' to see which detection step failed.
5. Set the proxy manually with `networksetup -setwebproxy <service> 127.0.0.1 <port>`.

const { execSync } = require('child_process')
function macHasNetworkService() {
  try {
    execSync('route -n get 0.0.0.0', { stdio: 'ignore' })
    const out = execSync('networksetup -listallnetworkservices', { encoding: 'utf8' })
    return out.split('\n').slice(1).some(l => l.trim() && !l.startsWith('*'))
  } catch { return false }
}
// call before setting the system proxy; if false, connect a network first

null

try {
  await setSystemProxy({ ip: '127.0.0.1', port })
} catch (e) {
  if (e.message.includes('未找到可用的 macOS 网络服务')) {
    console.error('Connect Wi-Fi/Ethernet (or disable VPN-only routing) and retry; see core.log "macOS 代理服务检测" lines')
  } else throw e
}

When it happens

Trigger: Calling the macOS set-system-proxy script when: no default route exists (offline / all interfaces down); `networksetup` is missing or fails; the route device (e.g. en0/utun) cannot be matched to any network service; the service list contains only disabled/VPN pseudo-services that pickMacNetworkService rejects.

Common situations: Running on a Mac with Wi-Fi off and only a VPN tunnel interface active; freshly provisioned macOS VMs with no network services enabled; broken/renamed network service configurations; networksetup unavailable in restricted environments.

Related errors

• 无效的代理 IP 地址: ${ip}
• 无效的代理端口号: ${port}
• macOS 代理服务检测：未通过设备名匹配到网络服务，尝试备用方法
• macOS 代理服务检测：获取网络服务列表失败:
• macOS 代理服务检测：未通过服务列表找到可用网络服务

AI-assisted analysis of docmirror/dev-sidecar@7710cd56cc (2026-08-31). Data as JSON: /api/errors/c4c9460e0d13a6a2. Report an issue: GitHub.