docmirror/dev-sidecar · warning

macOS 代理服务检测：未通过设备名匹配到网络服务，尝试备用方法

Error message

macOS 代理服务检测：未通过设备名匹配到网络服务，尝试备用方法

What it means

This is a non-fatal warning from getMacNetworkService() in the macOS system-proxy setup. The function runs `route -n get 0.0.0.0` to find the active network device, then `networksetup -listnetworkserviceorder` to map that device (e.g. en0) to a network service name (e.g. Wi-Fi). When the device was detected but no service line matching `Device: <device>` exists in the service order output, the code logs this warning and continues to the fallback strategy (`networksetup -listallnetworkservices`). It is not thrown; it only indicates the primary device-to-service mapping failed.

Source

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

    }
  }
  return services[0]
}

async function getMacNetworkService (exec) {
  try {
    const routeOutput = await exec('route -n get 0.0.0.0')
    const device = parseMacRouteDevice(routeOutput)
    if (device) {
      log.info('macOS 代理服务检测：当前网络设备:', device)
      try {
        const networkServiceOrder = await exec('networksetup -listnetworkserviceorder')
        const matchedService = parseMacNetworkServiceByDevice(networkServiceOrder, device)
        if (matchedService) {
          log.info('macOS 代理服务检测：通过设备名匹配到网络服务:', matchedService)
          return matchedService
        }
        log.warn('macOS 代理服务检测：未通过设备名匹配到网络服务，尝试备用方法')
      } catch (e) {
        log.warn('macOS 代理服务检测：获取网络服务列表失败:', e.message, '，尝试备用方法')
      }
    } else {
      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 代理服务检测：未通过服务列表找到可用网络服务')

View on GitHub (pinned to 7710cd56cc)

Solutions

  1. No action strictly required — the code automatically falls back to `networksetup -listallnetworkservices` and picks Wi-Fi/Ethernet
  2. Verify the active device with `route -n get 0.0.0.0` and confirm it appears in `networksetup -listnetworkserviceorder`; if it is a VPN (utun) device, disconnect the VPN or manually choose the real network service in DevSidecar proxy settings
  3. Update macOS/DevSidecar if `networksetup` output format no longer matches; check DevSidecar logs for which service was ultimately selected
Defensive patterns

Strategy: fallback

Validate before calling

const { execSync } = require('node:child_process')
function canMapDeviceToService() {
  try {
    const dev = execSync('route -n get 0.0.0.0').toString().match(/interface:\s*(\S+)/)?.[1]
    if (!dev) return false
    return execSync('networksetup -listnetworkserviceorder').toString().includes(`Device: ${dev}`)
  } catch { return false }
}

Type guard

function hasDeviceMatch(order, device) {
  return typeof order === 'string' && typeof device === 'string' &&
    order.split(/\r?\n/).some(l => l.includes(`Device: ${device}`))
}

Try / catch

try {
  const service = await setSystemProxy({ ip, port })
} catch (e) {
  if (e.message.includes('未找到可用的 macOS 网络服务')) {
    // fall back to manual proxy config or skip system-proxy
  }
}

Prevention

When it happens

Trigger: Called via executor.mac() during DevSidecar.api startup when setting the macOS system proxy. Specific triggers: the active interface name from `route -n get 0.0.0.0` (e.g. utun0, awdl0, bridge0, or a VPN tunnel device) has no corresponding entry in `networksetup -listnetworkserviceorder`, or the output format of networksetup changed across macOS versions so the `Device: enX` pattern no longer matches.

Common situations: Users on VPNs where the default route goes through a utun interface; users with unusually named services (e.g. localized Wi-Fi names, USB/Thunderbolt adapters) where the service order parser fails; macOS upgrades that alter `networksetup -listnetworkserviceorder` formatting.

Related errors

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