代理与 geoip

让浏览器通过你自己的代理出网，授权版构建还支持带用户名和密码的 SOCKS5；用 geoip 让时区、语言和 WebRTC 地址与代理的出口 IP 保持一致。

自动匹配代理所在地区（geoip）

在传入代理的同时传入 geoip，SDK 就会解析代理的出口 IP——在离线的 geoip-all-in-one 数据库中查询——并为该地区设置一致的时区 + navigator 首选语言 + Accept-Language + WebRTC IP。再也不用为每个代理手动匹配时区：

from clearcote import launch

browser = launch(
    fingerprint="user-7423",
    proxy={"server": "http://host:8080", "username": "u", "password": "p"},
    geoip=True,  # timezone + language auto-matched to the proxy's region
)

它还会为该地区设置地理位置和完整的 navigator.languages 列表，支持 HTTP 和 SOCKS5 代理（包括带凭据的代理），三个 SDK 都支持（.NET 中为 Geoip = true）。首次运行会下载该数据库（约 50 MB）。如果无法解析出地区，启动会以 GeoipError 中止，而不是悄悄用本机的时钟和语言启动；如果仍要启动，请同时设置 timezone 和 acceptLanguage。查询的时限为 20 秒（CLEARCOTE_GEOIP_TIMEOUT_SECONDS）；在 .NET 中，该错误为 GeoipException。如果既没有 geoip 也没有显式指定 timezone，时区会跟随语言——en-US 就意味着纽约时区，哪怕用的是德国代理。

想自己设置？使用 acceptLanguage（Node）/ accept_language（Python），例如 "en-US,en"——它会设置 Accept-Language 请求头、完整的 navigator.languages 数组以及 navigator.language——Intl / toLocaleString 也会随之变化。

带凭据的 SOCKS5

原版 Chromium 根本无法对 SOCKS5 代理进行认证——它没有实现用户名/密码子协商——所以常见的变通做法是使用一个保存凭据的本地中继。授权版构建在引擎中实现了这一功能（RFC 1929），因此无需中继。把用户名和密码作为单独的字段传入，或写在地址里（socks5://user:pass@host:port）；无论哪种方式，SDK 都会把它们交给引擎。写在地址里的凭据需要 SDK 0.31.1 或更新版本：旧版 SDK 会让 Playwright 把凭据丢掉，代理收不到任何登录信息。

from clearcote import launch_persistent_context

ctx = launch_persistent_context(
    "./profile",
    proxy={"server": "socks5://proxy.example.net:1080", "username": "user", "password": "pass"},
)
page = ctx.pages[0] if ctx.pages else ctx.new_page()
page.goto("https://api.ipify.org?format=json")   # confirm the exit IP is the proxy's

需要授权版构建（GitHub 免费版或 Pro，引擎 151 r14 或更新）；开源版构建无法对 SOCKS5 代理进行认证，因此请配合本地中继或 HTTP 代理使用。

在信任一个会话之前，务必先核实出口地址。代理如果静默失效并直接放行，流量就会从你自己的 IP 发出，其他所有防范措施都将失去意义。请在启动时用一个回显地址的服务检查一次，而不是想当然。