{"record":{"id":"e806b6ba03560e5d","repo":"docmirror/dev-sidecar","slug":"macos-e806b6","errorCode":null,"errorMessage":"macOS 代理服务检测：未通过设备名匹配到网络服务，尝试备用方法","messagePattern":"macOS 代理服务检测：未通过设备名匹配到网络服务，尝试备用方法","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"packages/core/src/shell/scripts/set-system-proxy/index.js","lineNumber":254,"sourceCode":"    }\n  }\n  return services[0]\n}\n\nasync function getMacNetworkService (exec) {\n  try {\n    const routeOutput = await exec('route -n get 0.0.0.0')\n    const device = parseMacRouteDevice(routeOutput)\n    if (device) {\n      log.info('macOS 代理服务检测：当前网络设备:', device)\n      try {\n        const networkServiceOrder = await exec('networksetup -listnetworkserviceorder')\n        const matchedService = parseMacNetworkServiceByDevice(networkServiceOrder, device)\n        if (matchedService) {\n          log.info('macOS 代理服务检测：通过设备名匹配到网络服务:', matchedService)\n          return matchedService\n        }\n        log.warn('macOS 代理服务检测：未通过设备名匹配到网络服务，尝试备用方法')\n      } catch (e) {\n        log.warn('macOS 代理服务检测：获取网络服务列表失败:', e.message, '，尝试备用方法')\n      }\n    } else {\n      log.warn('macOS 代理服务检测：未检测到当前网络设备，尝试备用方法')\n    }\n  } catch (e) {\n    log.warn('macOS 代理服务检测：获取路由信息失败:', e.message, '，尝试备用方法')\n  }\n\n  try {\n    const allServicesOutput = await exec('networksetup -listallnetworkservices')\n    const fallbackService = pickMacNetworkService(allServicesOutput)\n    if (fallbackService) {\n      log.info('macOS 代理服务检测：通过服务列表备用方法找到网络服务:', fallbackService)\n      return fallbackService\n    }\n    log.warn('macOS 代理服务检测：未通过服务列表找到可用网络服务')","sourceCodeStart":236,"sourceCodeEnd":272,"githubUrl":"https://github.com/docmirror/dev-sidecar/blob/7710cd56cce760c708f30b01d2d4056eb8c402d5/packages/core/src/shell/scripts/set-system-proxy/index.js#L236-L272","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["No action strictly required — the code automatically falls back to `networksetup -listallnetworkservices` and picks Wi-Fi/Ethernet","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","Update macOS/DevSidecar if `networksetup` output format no longer matches; check DevSidecar logs for which service was ultimately selected"],"exampleFix":null,"handlingStrategy":"fallback","validationCode":"const { execSync } = require('node:child_process')\nfunction canMapDeviceToService() {\n  try {\n    const dev = execSync('route -n get 0.0.0.0').toString().match(/interface:\\s*(\\S+)/)?.[1]\n    if (!dev) return false\n    return execSync('networksetup -listnetworkserviceorder').toString().includes(`Device: ${dev}`)\n  } catch { return false }\n}","typeGuard":"function hasDeviceMatch(order, device) {\n  return typeof order === 'string' && typeof device === 'string' &&\n    order.split(/\\r?\\n/).some(l => l.includes(`Device: ${device}`))\n}","tryCatchPattern":"try {\n  const service = await setSystemProxy({ ip, port })\n} catch (e) {\n  if (e.message.includes('未找到可用的 macOS 网络服务')) {\n    // fall back to manual proxy config or skip system-proxy\n  }\n}","preventionTips":["Keep the Mac connected to a physical/Wi-Fi network (not only a VPN utun) when enabling the proxy","Treat this warning as informational — verify which service the fallback picked in the logs","After macOS upgrades, re-test `networksetup -listnetworkserviceorder` output format"],"tags":["macos","networksetup","system-proxy","fallback"],"backgroundTag":"macos-network-service-not-found","analyzedSha":"7710cd56cce760c708f30b01d2d4056eb8c402d5","analyzedAt":"2026-08-31T22:07:07.234Z","schemaVersion":2},"datasetVersion":"2026-08-31T22:30:34.772Z"}