docmirror/dev-sidecar · error

无效的代理 IP 地址: ${ip}

Error message

无效的代理 IP 地址: ${ip}

What it means

validateProxyIp is a defence-in-depth guard on the macOS sudo execution path in set-system-proxy: the proxy host must be a string matching /^[\w.\-:[\]]+$/ (letters, digits, underscore, dot, hyphen, colon, brackets) before it is embedded in networksetup commands. Any other value — or one containing shell metacharacters, spaces, slashes, or an empty string — throws this error to prevent command injection and malformed config.

Source

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

/**
 * 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
 * value looks suspicious.  This is a defence-in-depth guard for the sudo
 * execution path; the primary protection is `shellEscapeArg`.
 */
function validateProxyIp (ip) {
  if (typeof ip !== 'string' || !/^[\w.\-:[\]]+$/.test(ip)) {
    throw new Error(`无效的代理 IP 地址: ${ip}`)
  }
}

/**
 * Strict-validate a TCP port number.
 */
function validateProxyPort (port) {
  const n = Number(port)
  if (!Number.isInteger(n) || n < 1 || n > 65535) {
    throw new Error(`无效的代理端口号: ${port}`)
  }
}

function sudoExecMac (cmd) {
  return new Promise((resolve, reject) => {
    log.info('以管理员权限执行命令:', cmd)
    sudoPrompt.exec(cmd, { name: 'dev-sidecar' }, (error, stdout, stderr) => {
      if (stderr) {

View on GitHub (pinned to 7710cd56cc)

Solutions

1. Set the proxy host to a bare hostname or IP without scheme: use `127.0.0.1`, not `http://127.0.0.1`.
2. Check ~/.dev-sidecar/config.json and the remote shared/personal config layers for a malformed ip/proxyHost value and fix it.
3. Remove any whitespace or special characters from the value (only [A-Za-z0-9_.-:[]) are accepted).
4. If you control the code, validate/normalize the host before invoking the script.

Example fix

// before
await api.shell.setSystemProxy({ ip: 'http://127.0.0.1', port: 31181 })
// after
await api.shell.setSystemProxy({ ip: '127.0.0.1', port: 31181 })

function isValidProxyIp(ip) {
  return typeof ip === 'string' && /^[\w.\-:[\]]+$/.test(ip)
}
const ip = '127.0.0.1'
if (!isValidProxyIp(ip)) throw new Error(`fix config: bad proxy ip ${JSON.stringify(ip)}`)

function isProxyIp(v) {
  return typeof v === 'string' && v.length > 0 && /^[\w.\-:[\]]+$/.test(v)
}

try {
  await setSystemProxy({ ip, port })
} catch (e) {
  if (e.message.includes('无效的代理 IP 地址')) {
    // strip scheme / trim and retry with a bare host
    const bare = String(ip).replace(/^https?:\/\//, '').split('/')[0].trim()
    if (isProxyIp(bare)) return setSystemProxy({ ip: bare, port })
  }
  throw e
}

When it happens

Trigger: Calling the macOS set-system-proxy script with proxy ip set to: undefined/null/non-string; an empty string from config; a value containing spaces, 'http://' scheme prefix, or shell metacharacters ($;|&); a URL like 'http://127.0.0.1' passed where only the bare host '127.0.0.1' is expected.

Common situations: User config (~/.dev-sidecar/config.json) holding 'proxyHost': 'http://127.0.0.1' or an empty value; typos in the settings UI; config merged from remote shared/personal layers containing a full URL instead of a host.

Related errors

• 无效的代理端口号: ${port}
• 未找到可用的 macOS 网络服务，无法设置系统代理
• FreeEye runtime config is required.
• Invalid version string: ${version}
• macOS 代理服务检测：未通过设备名匹配到网络服务，尝试备用方法

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