在 Swift 中使用代理：URLSession 代理配置与实战指南

在 Swift 中使用代理：为什么 iOS 开发者需要它

在 Swift 中使用代理（proxy）是 iOS 和 macOS 开发者在构建数据采集、API 测试或区域内容访问应用时经常遇到的需求。无论是 Swift 网页抓取、SERP 追踪，还是访问地理锁定的端点，URLSession 都原生支持通过 connectionProxyDictionary 配置 HTTP/HTTPS/SOCKS5 代理。然而，Apple 的代理认证机制存在已知缺陷——kCFProxyUsernameKey 和 kCFProxyPasswordKey 在 URLSession 上经常不可靠，导致 407 代理认证失败。本文将以代码优先的方式，逐步展示如何在 Swift 中正确配置 URLSession 代理，并通过 Proxy-Authorization 头或 URLSessionDelegate 方法解决认证问题。

ProxyHat 提供住宅、移动和数据中心代理，网关地址为 gate.proxyhat.com，HTTP 端口 8080，SOCKS5 端口 1080。虽然 ProxyHat 的官方 SDK 目前覆盖 Python 和 Node.js，但其网关协议完全兼容标准 HTTP/SOCKS5 代理，因此在 Swift 中只需使用原生 URLSession 即可接入。详见 ProxyHat 官方文档。

技术背景：为什么需要代理

许多 API 端点和网站会对请求来源 IP 进行限制。数据中心 IP 段通常被 CDN 和 WAF 提供商标记为高风险，导致请求被拦截或返回 403/429。住宅代理使用真实 ISP 分配的 IP 地址，请求看起来像来自普通用户，成功率显著提高。根据行业经验，住宅代理在抓取任务中的成功率通常比数据中心代理高 30%–50%，平均响应延迟约 200–800ms，而数据中心代理虽然延迟更低（50–150ms），但被封锁的概率也更高。

对于 iOS/macOS 开发者来说，代理的使用场景包括：

• SERP 抓取：从不同地理位置获取搜索引擎结果页，用于排名追踪和竞品分析。
• 电商价格监控：跨区域比较商品价格，需要来自不同国家 IP 的请求。
• 区域锁定内容：访问仅限特定国家/地区的内容或 API。
• QA 测试：从不同地理位置验证应用行为和 CDN 路由。

配置 URLSession 的 HTTP/HTTPS 代理

在 Swift 中配置代理的核心是 URLSessionConfiguration.connectionProxyDictionary。这是一个 [String: Any] 字典，使用 CFNetwork 定义的键来指定代理类型、主机和端口。

以下代码展示了如何创建一个配置了 ProxyHat HTTP 代理的 URLSession：

import Foundation

func makeProxiedSession(username: String, password: String) -> URLSession {
    let config = URLSessionConfiguration.ephemeral

    // 构建 Proxy-Authorization 凭据
    let credentials = "\(username):\(password)"
    let credData = credentials.data(using: .utf8)!
    let base64 = credData.base64EncodedString()

    config.connectionProxyDictionary = [
        // HTTP 代理
        kCFNetworkProxiesHTTPEnable as String: 1,
        kCFNetworkProxiesHTTPProxy as String: "gate.proxyhat.com",
        kCFNetworkProxiesHTTPPort as String: 8080,

        // HTTPS 代理（HTTPS 请求通过 CONNECT 隧道转发）
        kCFNetworkProxiesHTTPSEnable as String: 1,
        kCFNetworkProxiesHTTPSProxy as String: "gate.proxyhat.com",
        kCFNetworkProxiesHTTPSPort as String: 8080,
    ]

    // 由于 kCFProxyUsernameKey/PasswordKey 在 URLSession 上不可靠，
    // 我们通过自定义 HTTP 头注入认证信息。
    // 注意：此方法仅对 HTTP 请求有效；HTTPS 需要使用 delegate 方案（见下文）。
    config.httpAdditionalHeaders = [
        "Proxy-Authorization": "Basic \(base64)"
    ]

    return URLSession(configuration: config)
}

// 使用示例
let session = makeProxiedSession(
    username: "user-country-US-city-newyork-session-abc123",
    password: "your_password"
)

let url = URL(string: "https://httpbin.org/ip")!
let task = session.dataTask(with: url) { data, response, error in
    if let error = error {
        print("请求失败: \(error)")
        return
    }
    if let data = data, let body = String(data: data, encoding: .utf8) {
        print("响应: \(body)")
    }
}
task.resume()

地理定位与会话粘性

ProxyHat 的地理定位和会话控制通过用户名中的标志实现。例如：

• user-country-US — 使用美国 IP
• user-country-DE-city-berlin — 使用德国柏林 IP
• user-session-abc123 — 粘性会话，同一 session ID 在 TTL 内保持相同出口 IP

这些标志可以组合使用：user-country-US-city-newyork-session-abc123。

认证：解决 407 代理认证挑战

kCFProxyUsernameKey 和 kCFProxyPasswordKey 在 URLSession 上行为不一致，尤其是在 HTTPS 请求通过 CONNECT 隧道时。有两种可靠的替代方案：

方案一：Proxy-Authorization 头（仅 HTTP）

对于纯 HTTP 请求，在 httpAdditionalHeaders 中设置 Proxy-Authorization: Basic <base64> 头即可。但对于 HTTPS，httpAdditionalHeaders 不会在 CONNECT 请求中发送，因此此方法对 HTTPS 不完全可靠。

方案二：URLSessionDelegate 处理 407 挑战（推荐）

实现 urlSession(_:didReceive:completionHandler:) 方法来响应代理认证挑战。这是最可靠的方案，适用于 HTTP 和 HTTPS：

import Foundation

class ProxyAuthDelegate: NSObject, URLSessionDelegate {
    let proxyUsername: String
    let proxyPassword: String

    init(proxyUsername: String, proxyPassword: String) {
        self.proxyUsername = proxyUsername
        self.proxyPassword = proxyPassword
    }

    func urlSession(
        _ session: URLSession,
        didReceive challenge: URLAuthenticationChallenge,
        completionHandler: @escaping (URLSession.AuthChallengeDisposition, URLCredential?) -> Void
    ) {
        // 处理代理认证（407 Proxy Authentication Required）
        if challenge.protectionSpace.authenticationMethod == NSURLAuthenticationMethodHTTPProxy ||
           challenge.protectionSpace.authenticationMethod == NSURLAuthenticationMethodHTTPSProxy {
            let credential = URLCredential(
                user: proxyUsername,
                password: proxyPassword,
                persistence: .forSession
            )
            completionHandler(.useCredential, credential)
            return
        }

        // 处理 TLS 服务器证书验证（默认信任系统证书链）
        if challenge.protectionSpace.authenticationMethod == NSURLAuthenticationMethodServerTrust {
            if let trust = challenge.protectionSpace.serverTrust {
                completionHandler(.useCredential, URLCredential(trust: trust))
                return
            }
        }

        completionHandler(.performDefaultHandling, nil)
    }
}

func makeProxiedSessionWithDelegate(username: String, password: String) -> URLSession {
    let config = URLSessionConfiguration.ephemeral
    config.connectionProxyDictionary = [
        kCFNetworkProxiesHTTPEnable as String: 1,
        kCFNetworkProxiesHTTPProxy as String: "gate.proxyhat.com",
        kCFNetworkProxiesHTTPPort as String: 8080,
        kCFNetworkProxiesHTTPSEnable as String: 1,
        kCFNetworkProxiesHTTPSProxy as String: "gate.proxyhat.com",
        kCFNetworkProxiesHTTPSPort as String: 8080,
    ]

    let delegate = ProxyAuthDelegate(proxyUsername: username, proxyPassword: password)
    return URLSession(configuration: config, delegate: delegate, delegateQueue: nil)
}

// 使用示例：美国纽约出口 IP + 粘性会话
let session2 = makeProxiedSessionWithDelegate(
    username: "user-country-US-city-newyork-session-abc123",
    password: "your_password"
)

关键提示：对于 HTTPS 请求，务必使用 delegate 方案而非 httpAdditionalHeaders。HTTPS 的 CONNECT 隧道建立时，httpAdditionalHeaders 不会被发送，只有 delegate 方法能正确处理代理认证挑战。

配置 SOCKS5 代理

ProxyHat 还支持 SOCKS5 代理，端口为 1080。SOCKS5 代理在 URLSession 中通过 kCFStreamPropertySOCKSProxy* 系列键来配置。SOCKS5 的认证同样需要通过 delegate 处理：

import Foundation

func makeSOCKS5Session(username: String, password: String) -> URLSession {
    let config = URLSessionConfiguration.ephemeral
    config.connectionProxyDictionary = [
        kCFNetworkProxiesSOCKSEnable as String: 1,
        kCFStreamPropertySOCKSProxyHost as String: "gate.proxyhat.com",
        kCFStreamPropertySOCKSProxyPort as String: 1080,
        kCFStreamPropertySOCKSVersion as String: kCFStreamSocketSOCKSVersion5 as String,
        kCFStreamPropertySOCKSUser as String: username,
        kCFStreamPropertySOCKSPassword as String: password,
    ]

    // SOCKS5 认证也可能需要 delegate 作为后备
    let delegate = ProxyAuthDelegate(proxyUsername: username, proxyPassword: password)
    return URLSession(configuration: config, delegate: delegate, delegateQueue: nil)
}

let socksSession = makeSOCKS5Session(
    username: "user-country-DE-city-berlin",
    password: "your_password"
)

住宅代理 vs 数据中心代理 vs 移动代理

选择正确的代理类型对 Swift 网页抓取的成功率至关重要。以下是三种代理类型的对比：

对于大多数 iOS/macOS 应用场景，住宅代理是性价比和可靠性的最佳平衡点。查看 ProxyHat 可用地区 了解支持的地理定位选项。

async/await 并发抓取示例

Swift 5.5+ 的 async/await 和 TaskGroup 非常适合并发代理请求场景。以下示例展示如何使用 URLSession.shared.data(for:) 发起并发请求，解码 JSON 响应，并实现基本的错误处理：

import Foundation

// 数据模型
struct IPResponse: Codable {
    let origin: String
}

struct ScrapedResult: Codable {
    let url: String
    let status: Int
    let bodyPreview: String
}

// 代理配置构建器
func makeProxyConfig(country: String, session: String) -> URLSessionConfiguration {
    let config = URLSessionConfiguration.ephemeral
    config.connectionProxyDictionary = [
        kCFNetworkProxiesHTTPEnable as String: 1,
        kCFNetworkProxiesHTTPProxy as String: "gate.proxyhat.com",
        kCFNetworkProxiesHTTPPort as String: 8080,
        kCFNetworkProxiesHTTPSEnable as String: 1,
        kCFNetworkProxiesHTTPSProxy as String: "gate.proxyhat.com",
        kCFNetworkProxiesHTTPSPort as String: 8080,
    ]
    config.timeoutIntervalForRequest = 30
    config.timeoutIntervalForResource = 60
    config.httpMaximumConnectionsPerHost = 10
    return config
}

// 带重试的请求函数
func fetchWithRetry(
    url: URL,
    session: URLSession,
    maxRetries: Int = 3
) async throws -> (Data, HTTPURLResponse) {
    var lastError: Error?

    for attempt in 0..<maxRetries {
        do {
            let (data, response) = try await session.data(from: url)
            guard let httpResponse = response as? HTTPURLResponse else {
                throw URLError(.badServerResponse)
            }

            // 对 429/503 进行重试
            if httpResponse.statusCode == 429 || httpResponse.statusCode == 503 {
                let delay = pow(2.0, Double(attempt)) // 指数退避：1s, 2s, 4s
                try await Task.sleep(nanoseconds: UInt64(delay * 1_000_000_000))
                continue
            }

            return (data, httpResponse)
        } catch {
            lastError = error
            let delay = pow(2.0, Double(attempt))
            try await Task.sleep(nanoseconds: UInt64(delay * 1_000_000_000))
        }
    }

    throw lastError ?? URLError(.unknown)
}

// 并发抓取多个 URL
func scrapeConcurrently(urls: [URL], proxyUsername: String, proxyPassword: String) async -> [ScrapedResult] {
    let config = makeProxyConfig(country: "US", session: "batch-001")
    let delegate = ProxyAuthDelegate(proxyUsername: proxyUsername, proxyPassword: proxyPassword)
    let session = URLSession(configuration: config, delegate: delegate, delegateQueue: nil)

    // 使用 TaskGroup 并发请求，限制并发度
    let results = await withTaskGroup(of: ScrapedResult?.self) { group in
        for url in urls {
            group.addTask {
                do {
                    let (data, response) = try await fetchWithRetry(url: url, session: session)
                    let bodyPreview = String(data: data.prefix(500), encoding: .utf8) ?? ""
                    return ScrapedResult(
                        url: url.absoluteString,
                        status: response.statusCode,
                        bodyPreview: bodyPreview
                    )
                } catch {
                    print("抓取失败 \(url): \(error)")
                    return nil
                }
            }
        }

        var collected: [ScrapedResult] = []
        for await result in group {
            if let r = result {
                collected.append(r)
            }
        }
        return collected
    }

    return results
}

// 使用示例
let urls = [
    URL(string: "https://httpbin.org/ip")!,
    URL(string: "https://httpbin.org/headers")!,
    URL(string: "https://httpbin.org/user-agent")!,
]

Task {
    let results = await scrapeConcurrently(
        urls: urls,
        proxyUsername: "user-country-US-session-batch001",
        proxyPassword: "your_password"
    )
    for r in results {
        print("\(r.status) — \(r.url): \(r.bodyPreview.prefix(100))")
    }
}

curl 验证代理连通性

在 Swift 代码之前，建议先用 curl 验证代理配置是否正确：

# HTTP 代理验证
# 注意：curl 的 -U 参数用于代理认证
curl -x http://gate.proxyhat.com:8080 \
  -U "user-country-US-city-newyork-session-test1:your_password" \
  https://httpbin.org/ip

# SOCKS5 代理验证
curl -x socks5://gate.proxyhat.com:1080 \
  -U "user-country-DE-city-berlin:your_password" \
  https://httpbin.org/ip

生产环境最佳实践

TLS 服务器证书处理

在代理环境中，TLS 握手发生在代理隧道内。默认情况下，URLSession 会验证服务器证书。如果你需要自定义证书验证逻辑（例如使用自签名证书进行测试），可以在 delegate 中实现：

class TLSAwareDelegate: NSObject, URLSessionDelegate {
    let proxyUsername: String
    let proxyPassword: String
    let allowSelfSigned: Bool

    init(proxyUsername: String, proxyPassword: String, allowSelfSigned: Bool = false) {
        self.proxyUsername = proxyUsername
        self.proxyPassword = proxyPassword
        self.allowSelfSigned = allowSelfSigned
    }

    func urlSession(
        _ session: URLSession,
        didReceive challenge: URLAuthenticationChallenge,
        completionHandler: @escaping (URLSession.AuthChallengeDisposition, URLCredential?) -> Void
    ) {
        let space = challenge.protectionSpace

        // 代理认证
        if space.authenticationMethod == NSURLAuthenticationMethodHTTPProxy ||
           space.authenticationMethod == NSURLAuthenticationMethodHTTPSProxy {
            completionHandler(.useCredential, URLCredential(
                user: proxyUsername,
                password: proxyPassword,
                persistence: .forSession
            ))
            return
        }

        // TLS 服务器信任
        if space.authenticationMethod == NSURLAuthenticationMethodServerTrust {
            guard let trust = space.serverTrust else {
                completionHandler(.cancelAuthenticationChallenge, nil)
                return
            }

            if allowSelfSigned {
                // 仅用于测试环境！生产环境切勿如此。
                completionHandler(.useCredential, URLCredential(trust: trust))
            } else {
                // 生产环境：验证证书链
                var error: CFError?
                let isValid = SecTrustEvaluateWithError(trust, &error)
                if isValid {
                    completionHandler(.useCredential, URLCredential(trust: trust))
                } else {
                    completionHandler(.cancelAuthenticationChallenge, nil)
                }
            }
            return
        }

        completionHandler(.performDefaultHandling, nil)
    }
}

指数退避重试策略

代理请求可能因网络抖动、IP 轮换或目标站点的速率限制而失败。实现指数退避重试是关键的生产级策略：

import Foundation

enum ProxyError: Error {
    case maxRetriesExceeded
    case invalidResponse
}

func fetchWithExponentialBackoff(
    url: URL,
    session: URLSession,
    maxRetries: Int = 5,
    baseDelay: TimeInterval = 1.0
) async throws -> Data {
    var lastError: Error?

    for attempt in 0..<maxRetries {
        do {
            let (data, response) = try await session.data(from: url)
            guard let http = response as? HTTPURLResponse else {
                throw ProxyError.invalidResponse
            }

            switch http.statusCode {
            case 200...299:
                return data
            case 429:
                // 检查 Retry-After 头
                let retryAfter = http.value(forHTTPHeaderField: "Retry-After")
                let delay = TimeInterval(retryAfter ?? "") ?? baseDelay * pow(2.0, Double(attempt))
                try await Task.sleep(nanoseconds: UInt64(delay * 1_000_000_000))
            case 500...599:
                let delay = baseDelay * pow(2.0, Double(attempt))
                try await Task.sleep(nanoseconds: UInt64(delay * 1_000_000_000))
            default:
                return data // 返回非 2xx 响应体供调用方处理
            }
        } catch {
            lastError = error
            let delay = baseDelay * pow(2.0, Double(attempt))
            try await Task.sleep(nanoseconds: UInt64(delay * 1_000_000_000))
        }
    }

    throw lastError ?? ProxyError.maxRetriesExceeded
}

App Transport Security (ATS)

iOS 9+ 引入了 App Transport Security (ATS)，要求所有网络连接使用 TLS 1.2+。通过 HTTP 代理访问 HTTPS 端点时，URLSession 会先与代理建立 TCP 连接，然后发送 CONNECT 请求建立隧道，最后在隧道内进行 TLS 握手。ATS 仍然会验证最终目标服务器的 TLS 证书，因此不需要在 Info.plist 中禁用 ATS。

如果你遇到 ATS 相关错误，检查以下几点：

• 确保目标站点使用 TLS 1.2 或更高版本。
• 不要在 Info.plist 中全局禁用 ATS（NSAllowsArbitraryLoads），这会导致 App Store 审核被拒。
• 如果必须访问不支持 ATS 的端点，使用 NSExceptionDomains 进行针对性例外配置。

设备端隐私注意事项

• 使用 URLSessionConfiguration.ephemeral 避免将代理凭据写入磁盘缓存。
• 不要将代理密码硬编码在应用中——使用 Keychain 或服务端动态下发。
• 在 iOS 上，代理配置仅影响使用该 URLSession 实例的请求，不会影响系统全局网络。
• 遵循 App Store 审核指南，确保你的应用用途合法合规。

伦理与法律考量

使用代理进行数据采集时，务必注意法律和伦理边界：

• 优先使用官方 API：如果目标平台提供官方 API，应优先使用而非抓取网页。
• 遵守 robots.txt：尊重目标站点的爬虫协议。
• 美国 CFAA：美国《计算机欺诈和滥用法》可能适用于未经授权的访问。仅采集公开可访问的数据。
• 欧盟 GDPR：如果采集的数据涉及欧盟用户的个人数据，需遵守 GDPR 规定。参考 欧盟委员会数据保护页面。
• App Store 政策：Apple 对应用行为有严格规定，确保你的应用不会进行恶意抓取或违反目标平台的服务条款。
• 速率控制：即使使用代理，也应对目标站点保持合理的请求频率，避免造成服务压力。

ProxyHat 配置速查

以下是 ProxyHat 网关的完整连接参数：

ProxyHat 的 Python 和 Node.js SDK 使用相同的网关协议。Swift 开发者可以直接使用原生 URLSession 接入，无需额外 SDK。查看 ProxyHat 定价方案 选择适合的代理类型。

关键要点

• 使用 connectionProxyDictionary 配置 HTTP/HTTPS/SOCKS5 代理，指向 gate.proxyhat.com:8080（HTTP）或 :1080（SOCKS5）。
• 避免 kCFProxyUsernameKey：在 URLSession 上不可靠，改用 Proxy-Authorization 头（仅 HTTP）或 URLSessionDelegate 处理 407 挑战（推荐，兼容 HTTPS）。
• 地理定位通过用户名：user-country-US-city-newyork-session-abc123。
• 住宅代理适合需要高成功率的抓取任务，数据中心代理适合低延迟高并发场景。
• 生产环境必备：指数退避重试、ephemeral 配置、Keychain 存储凭据、遵守 ATS。
• 合规优先：优先使用官方 API，遵守 robots.txt、CFAA、GDPR 和 App Store 政策。

更多使用场景请参考 网页抓取用例 和 SERP 追踪用例。