自动化 API 参考

NestBrowser 提供本地 REST API，允许你通过代码控制浏览器环境。该 API 兼容 ChromeDriver 标准，因此可与 Selenium、Puppeteer、Playwright 以及几乎所有自动化框架协同使用。

🔒 API 功能仅在专业版和企业版中可用。

工作原理

1. NestBrowser 在本地运行一个 HTTP 服务（默认：http://localhost:19222）
2. 调用 API 启动环境 — NestBrowser 启动浏览器并返回 WebSocket 调试 URL
3. 你的自动化代码通过标准 WebDriver 协议连接到该 URL
4. 浏览器以完整的 NestBrowser 指纹配置运行

启动 API 服务

1. 打开 NestBrowser → 设置 → API
2. 开启启用 API 开关
3. 记下 API 端口（默认：19222）

基本 API 用法

启动环境

POST http://localhost:19222/api/v1/browser/start
Content-Type: application/json

{
  "profile_id": "你的环境ID"
}

响应：

{
  "code": 0,
  "data": {
    "ws": {
      "puppeteer": "ws://localhost:9222/devtools/browser/abc123",
      "selenium": "ws://localhost:9222/devtools/browser/abc123"
    },
    "http": "http://localhost:9222",
    "webdriver": "http://localhost:9222"
  }
}

停止环境

POST http://localhost:19222/api/v1/browser/stop
Content-Type: application/json

{
  "profile_id": "你的环境ID"
}

列出所有环境

GET http://localhost:19222/api/v1/profiles

与 Puppeteer 配合使用

const puppeteer = require('puppeteer-core');

async function main() {
  // 1. 通过 NestBrowser API 启动环境
  const response = await fetch('http://localhost:19222/api/v1/browser/start', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ profile_id: '你的环境ID' })
  });
  const { data } = await response.json();

  // 2. 将 Puppeteer 连接到运行中的浏览器
  const browser = await puppeteer.connect({
    browserWSEndpoint: data.ws.puppeteer,
    defaultViewport: null
  });

  // 3. 控制浏览器
  const page = await browser.newPage();
  await page.goto('https://example.com');
  console.log(await page.title());

  // 4. 完成后停止环境
  await browser.disconnect();
  await fetch('http://localhost:19222/api/v1/browser/stop', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ profile_id: '你的环境ID' })
  });
}

main();

与 Playwright 配合使用

import asyncio
from playwright.async_api import async_playwright
import httpx

async def main():
    # 1. 启动环境
    async with httpx.AsyncClient() as client:
        r = await client.post('http://localhost:19222/api/v1/browser/start',
            json={'profile_id': '你的环境ID'})
        ws_url = r.json()['data']['ws']['puppeteer']

    # 2. 连接 Playwright
    async with async_playwright() as p:
        browser = await p.chromium.connect_over_cdp(ws_url)
        page = browser.contexts[0].pages[0]
        await page.goto('https://example.com')
        print(await page.title())

asyncio.run(main())

与 Selenium 配合使用

from selenium import webdriver
from selenium.webdriver.chrome.options import Options
import requests

# 1. 启动环境
response = requests.post('http://localhost:19222/api/v1/browser/start',
    json={'profile_id': '你的环境ID'})
debugger_url = response.json()['data']['http']

# 2. 通过 Chrome DevTools Protocol 连接 Selenium
options = Options()
options.add_experimental_option('debuggerAddress', debugger_url.replace('http://', ''))

driver = webdriver.Chrome(options=options)
driver.get('https://example.com')
print(driver.title)

API 接口汇总

认证方式

本地 API 默认不需要认证（仅允许 localhost 访问）。如需在生产环境使用，可在 设置 → API → 启用 API Key 中开启认证。

GET http://localhost:19222/api/v1/profiles
X-NestBrowser-Token: 你的API密钥

环境相关接口

接口	方法	说明
/api/v1/profiles	GET	获取所有环境列表
/api/v1/browser/start	POST	启动指定环境
/api/v1/browser/stop	POST	停止指定环境
/api/v1/browser/active	GET	获取运行中的环境列表

启动环境参数

{
  "profile_id": "字符串",        // 必填
  "headless": false,             // 无头模式（默认：false）
  "args": ["--mute-audio"],      // 额外的 Chrome 启动参数
  "load_extensions": true        // 是否加载环境扩展程序
}

使用限制

• 专业版最多同时运行 10 个环境
• 企业版最多同时运行 50 个环境
• API 请求频率：每分钟 100 次

常见问题排查

API 返回”连接被拒绝”： 请确认已在 NestBrowser 设置中启用 API，且本地服务正在运行。

自动化过程中浏览器断开连接： 浏览器仍在运行，只是 WebSocket 连接超时了。重新使用相同的启动接口即可重新连接。

指纹未应用到自动化浏览器： 确保通过 API 返回的 WebSocket URL 进行连接（而非直接启动 Chrome）。指纹注入在 NestBrowser 层面完成。