docmirror/dev-sidecar · warning

macOS 代理服务检测：未通过服务列表找到可用网络服务

Error message

macOS 代理服务检测：未通过服务列表找到可用网络服务

What it means

Non-fatal warning from the fallback stage of getMacNetworkService(). Both primary strategies failed, so the code listed all services via `networksetup -listallnetworkservices` and ran pickMacNetworkService(), which returned null (empty or unusable list). This warning is logged just before the function throws the fatal Error '未找到可用的 macOS 网络服务，无法设置系统代理'.

Source

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

        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 代理服务检测：未通过服务列表找到可用网络服务')
  } 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) {

View on GitHub (pinned to 7710cd56cc)

Solutions

  1. Recreate a network service in System Settings > Network (add Wi-Fi or Ethernet service) so networksetup can report at least one service
  2. Verify with `networksetup -listallnetworkservices` that at least one real service name is printed; if not, repair network configuration or reset NVRAM/network settings
  3. If automatic proxy setup cannot work, set the macOS proxy manually (System Settings > Network > Proxies) or skip the proxy.enable option in DevSidecar config
Defensive patterns

Strategy: validation

Validate before calling

const { execSync } = require('node:child_process')
function hasNetworkServices() {
  try {
    const out = execSync('networksetup -listallnetworkservices').toString()
    const services = out.split(/\r?\n/).map(s => s.replace(/^\*/, '').trim())
      .filter(s => s && !s.startsWith('An asterisk'))
    return services.length > 0
  } catch { return false }
}
if (!hasNetworkServices()) throw new Error('No macOS network services configured; create one in System Settings')

Type guard

function extractServices(output) {
  if (typeof output !== 'string') return []
  return output.split(/\r?\n/).map(s => s.replace(/^\*/, '').trim())
    .filter(s => s && !s.startsWith('An asterisk (*) denotes'))
}

Try / catch

try {
  await DevSidecar.api.config.set('proxy.enable', true)
} catch (e) {
  if (e.message.includes('未找到可用的 macOS 网络服务')) {
    // guide user to recreate a network service or set proxy manually
  }
}

Prevention

When it happens

Trigger: `networksetup -listallnetworkservices` returns output containing only the asterisk legend line ('An asterisk (*) denotes...') and no service names, or an empty string — i.e. the system reports no network services at all.

Common situations: Macs with all network services deleted in System Settings > Network; corrupted network configuration; headless/virtualized macOS images with no configured interfaces.

Related errors

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