{"record":{"id":"c4c9460e0d13a6a2","repo":"docmirror/dev-sidecar","slug":"macos","errorCode":null,"errorMessage":"未找到可用的 macOS 网络服务，无法设置系统代理","messagePattern":"未找到可用的 macOS 网络服务，无法设置系统代理","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/core/src/shell/scripts/set-system-proxy/index.js","lineNumber":277,"sourceCode":"      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 代理服务检测：未通过服务列表找到可用网络服务')\n  } catch (e) {\n    log.warn('macOS 代理服务检测：获取所有网络服务列表失败:', e.message)\n  }\n\n  throw new Error('未找到可用的 macOS 网络服务，无法设置系统代理')\n}\n\n// macOS exit code 14 = \"You don't have permission to change the system preferences.\"\nconst MACOS_NETWORKSETUP_PERMISSION_ERROR_CODE = 14\n\n/**\n * POSIX single-quote escaping: wraps `arg` in single quotes, escaping any\n * embedded single quotes with the '\\''-idiom.  This prevents shell\n * metacharacter expansion regardless of the character set of the value.\n * @param {string|number} arg\n * @returns {string}\n */\nfunction shellEscapeArg (arg) {\n  return \"'\" + String(arg).replace(/'/g, \"'\\\\''\") + \"'\"\n}\n\n/**\n * Strict-validate a proxy host (IPv4 / IPv6 / hostname) and throw if the","sourceCodeStart":259,"sourceCodeEnd":295,"githubUrl":"https://github.com/docmirror/dev-sidecar/blob/7710cd56cce760c708f30b01d2d4056eb8c402d5/packages/core/src/shell/scripts/set-system-proxy/index.js#L259-L295","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Enable/connect a real network interface (turn Wi-Fi on or plug Ethernet) so a default route and service exist, then retry.","Verify manually: `route -n get 0.0.0.0` shows a device, and `networksetup -listallnetworkservices` lists an enabled service.","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.","Check the core.log lines starting with 'macOS 代理服务检测' to see which detection step failed.","Set the proxy manually with `networksetup -setwebproxy <service> 127.0.0.1 <port>`."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"const { execSync } = require('child_process')\nfunction macHasNetworkService() {\n  try {\n    execSync('route -n get 0.0.0.0', { stdio: 'ignore' })\n    const out = execSync('networksetup -listallnetworkservices', { encoding: 'utf8' })\n    return out.split('\\n').slice(1).some(l => l.trim() && !l.startsWith('*'))\n  } catch { return false }\n}\n// call before setting the system proxy; if false, connect a network first","typeGuard":"null","tryCatchPattern":"try {\n  await setSystemProxy({ ip: '127.0.0.1', port })\n} catch (e) {\n  if (e.message.includes('未找到可用的 macOS 网络服务')) {\n    console.error('Connect Wi-Fi/Ethernet (or disable VPN-only routing) and retry; see core.log \"macOS 代理服务检测\" lines')\n  } else throw e\n}","preventionTips":["Ensure an active interface with a default route (Wi-Fi/Ethernet) before enabling the system proxy.","Avoid relying on the proxy while only a VPN utun interface is up.","Check networksetup -listallnetworkservices returns at least one enabled service.","Inspect core.log 'macOS 代理服务检测' warnings to see which detection step failed."],"tags":["mac","system-proxy","networksetup","network-detection"],"backgroundTag":"no-active-network-service","analyzedSha":"7710cd56cce760c708f30b01d2d4056eb8c402d5","analyzedAt":"2026-08-31T22:07:07.234Z","schemaVersion":2},"datasetVersion":"2026-08-31T22:30:34.772Z"}