# 代理快速开始

> 在接入真实流量之前，先找到代理凭据、发送一个测试请求并确认出口 IP。

Canonical URL: https://s1.dev/zh/docs/proxies/quickstart

Search1API 提供两类代理：

- **动态住宅代理**：一个网关入口，通过全球住宅 IP 转发你的流量。按流量（GB）计费。
- **静态 ISP 代理**：整个订单期间使用固定 IP。每个 IP 都有各自的连接信息。

两者都使用用户名和密码认证，并支持 HTTP 和 SOCKS5。不提供 IP 白名单认证方式。

> **warn:** 代理凭据与 Search1API API 密钥相互独立。请始终连接代理页面上显示的 **Host** 和**端口**。**出口 IP** 是目标网站看到的地址，不是连接地址，你的凭据对它无效。

<Steps>

<Step>

### 打开你的代理

前往 [app.s1.dev/proxies](https://app.s1.dev/proxies)，在**您的代理**下打开对应的代理。

- **动态住宅代理**：连接信息位于**网关入口**卡片中。
- **静态 ISP 代理**：从 **IP 列表**中打开一个 IP，连接信息位于**代理 IP 信息**中。

</Step>

<Step>

### 选择协议并复制连接

在**连接协议**下选择 **HTTP** 或 **SOCKS5**。除非你的工具明确需要 SOCKS5，否则请使用 HTTP。静态 IP 的 Host 和端口可能因协议而异，因此请在选择协议后再复制。

使用动态网关时，请先设置**出口国家/地区**和 **IP 模式**。这些选项会改变密码，因此请在设置完成后再复制连接。详见[动态代理参数](https://s1.dev/zh/docs/proxies/parameters)。

点击**复制连接**，并选择你的工具所需的格式：

| 格式 | 典型用途 |
| --- | --- |
| `protocol://username:password@host:port` | curl、代码、大多数 HTTP 库 |
| `host:port:username:password` | 指纹浏览器和批量导入字段 |
| `username:password@host:port` | 需要单独填写协议的工具 |

</Step>

<Step>

### 发送测试请求

将占位符替换为你复制的值：

```bash
curl -x "http://USERNAME:PASSWORD@HOST:PORT" https://ipinfo.io/json
```

使用 SOCKS5 时，请使用 `socks5h://`，让代理同时负责 DNS 解析：

```bash
curl -x "socks5h://USERNAME:PASSWORD@HOST:PORT" https://ipinfo.io/json
```

代理正常工作时会返回 JSON，其中的 `ip` 和 `country` 就是目标网站看到的信息：

- **静态 ISP 代理**：`ip` 与仪表盘中的**出口 IP** 一致。
- **动态住宅代理**：再次运行该命令会返回不同的 `ip`，除非你选择了**保持同一 IP**。

如果返回的是错误，请在[故障排查](https://s1.dev/zh/docs/proxies/troubleshooting)中查找。

</Step>

<Step>

### 在代码中使用代理

即使目标网站使用 HTTPS，代理 URL 也始终以 `http://` 或 `socks5h://` 开头。

<Tabs items={['Python', 'Node.js', 'Playwright']}>

<Tab value="Python">

```python
import requests

proxy = "http://USERNAME:PASSWORD@HOST:PORT"
proxies = {"http": proxy, "https": proxy}

response = requests.get("https://ipinfo.io/json", proxies=proxies, timeout=30)
print(response.json())
```

两个键都指向同一个 `http://` URL。使用 SOCKS5 时，请安装 `requests[socks]` 并使用 `socks5h://`。

</Tab>

<Tab value="Node.js">

```js
import { ProxyAgent, fetch } from 'undici';

const dispatcher = new ProxyAgent('http://USERNAME:PASSWORD@HOST:PORT');
const response = await fetch('https://ipinfo.io/json', { dispatcher });
console.log(await response.json());
```

</Tab>

<Tab value="Playwright">

```js
import { chromium } from 'playwright';

const browser = await chromium.launch({
  proxy: {
    server: 'http://HOST:PORT',
    username: 'USERNAME',
    password: 'PASSWORD',
  },
});
const page = await browser.newPage();
await page.goto('https://ipinfo.io/json');
console.log(await page.textContent('body'));
await browser.close();
```

在 Playwright 中请使用 HTTP。Chromium 不支持需要用户名和密码认证的 SOCKS5 代理。

</Tab>

</Tabs>

</Step>

</Steps>

## 上线生产环境之前

- 空闲连接会在 5 分钟后关闭。长连接断开时请重新连接。
- 动态住宅代理的流量同时计算上传和下载。月度额度用完后，新连接会被拒绝，直到下一个计费周期。可在**带宽**卡片中查看用量。
- 使用静态 ISP 代理 Pro 和 Premium 时，请将每个 IP 的并发连接数控制在约 90 以内。超过 100 时，新连接可能会被拒绝。
- 目标端口 `80` 和 `443` 在所有 IP 上都可用；其他端口可能会以 `403 Tunnel Failed` 被拒绝。不要把代理当作全设备 VPN 使用：在 Clash、Shadowrocket 或 Surge 中请使用规则模式，只让需要的网站走代理。详见[被拦截的端口和网站](https://s1.dev/zh/docs/proxies/troubleshooting#blocked-ports-and-sites-403-tunnel-failed)。
- 将连接超时设置为至少 30 秒，并在新连接上以退避策略重试。
- 部分类别的网站（银行与支付、加密货币交易所、部分政府网站）以及邮件发送（SMTP，25 端口）可能无法使用。

## 后续步骤

- [动态代理参数](https://s1.dev/zh/docs/proxies/parameters): 指定出口国家/地区，并通过粘性会话保持同一 IP。

- [故障排查](https://s1.dev/zh/docs/proxies/troubleshooting): 解决 407、503、超时以及 IP 意外变化等问题。