连接分三步：服务开启、环境拉起、调试接管
Local API 连接指定浏览器环境的核心逻辑是通过本地 HTTP 接口拉起带独立指纹的浏览器内核，再把 CDP（Chrome DevTools Protocol）调试权限交给自动化脚本。完整流程包括三个环节：
- 在本地指纹浏览器客户端开启 Local API 服务，获取监听端口与鉴权密钥
- 向启动接口传入指定环境的唯一 ID，服务端拉起浏览器并返回调试地址
- 用 Puppeteer、Playwright 或 Selenium 连接返回的 CDP 地址，接管浏览器控制权
任务执行完需要调用关闭接口释放进程，否则多开窗口会挤占系统资源。
第一步：开启 API 服务并获取访问信息
Local API 是本地 HTTP 服务，必须在指纹浏览器桌面客户端保持启动登录的状态下才能工作。
进入客户端的系统设置或自动化配置面板，确认 Local API 服务已开启。记录两个关键信息：
- 本地服务地址：通常是
http://127.0.0.1:端口号或http://localhost:端口号，端口号因产品而异，部分工具支持自定义 - 身份凭证：API Key 或 Access Token，用于请求鉴权
部分指纹浏览器在首次开启 Local API 时会弹窗显示这些信息，建议截图保存。如果客户端未提供可视化开关，需查阅官方接口文档确认服务启动方式。
以 NexBrowser 为例，它在中国站的定位里明确提供免费不限调用的 Local API，适合入门用户测试与小规模自动化任务。安装客户端后，在自动化配置区域可以找到 API 服务的启用开关与本地地址。具体端口和路由定义需参考 NexBrowser 官方提供的开发接口文档。
易卡点 1：如果本地服务地址访问不通，先检查客户端是否保持登录、防火墙是否拦截本地回环端口、杀毒软件是否屏蔽进程通信。
第二步：传环境 ID 拉起指定浏览器
Local API 定位浏览器环境依赖的是唯一的环境 ID（如 profile_id、user_id 或 env_id），而不是客户端列表中显示的自定义名称或排序序号。
环境 ID 通常在创建浏览器环境后由系统自动生成，可以在客户端的环境列表、环境详情页或通过 API 提供的查询接口获取。如果手头只有环境名称，需要先调用列表接口拿到完整的环境 ID 映射表。
拿到目标环境 ID 后，向 Local API 的启动接口发送 HTTP 请求（通常是 GET 或 POST），请求参数至少包括：
- 环境 ID（必须显式传参）
- API Key 或 Token（用于鉴权）
请求示例的参数结构因产品而异，部分工具还支持在启动时传入无头模式、窗口尺寸等附加参数。
服务端接收请求后，会拉起一个具备独立指纹参数、绑定指定代理的浏览器内核进程，并在响应数据中返回：
- CDP 调试连接串（WebSocket Endpoint）：格式如
ws://127.0.0.1:调试端口/devtools/browser/...，供 Puppeteer 和 Playwright 使用 - 调试端口（Debugger Address）：如
127.0.0.1:调试端口，供 Selenium 使用
响应通常是 JSON 格式，包含启动状态、调试地址、环境元数据等字段。成功拉起后，对应环境的浏览器窗口会在本地显示（除非启用无头模式）。
易卡点 2：如果启动接口返回错误，常见原因包括环境 ID 不存在、该环境已被其他进程占用、绑定的代理服务器无法连接、或当前账号的窗口容量已用完。检查时优先确认 ID 拼写正确，再排查客户端是否有其他窗口正在使用该环境。
第三步：通过 CDP 调试地址接管自动化
拿到上一步返回的 CDP 调试地址后,根据自动化工具的不同选择对应的连接方式：
Puppeteer 连接
使用 puppeteer.connect() 方法，传入 WebSocket Endpoint：
const puppeteer = require('puppeteer-core');
const browser = await puppeteer.connect({
browserWSEndpoint: 'ws://127.0.0.1:调试端口/devtools/browser/...',
defaultViewport: null
});
const page = (await browser.pages())[0];注意使用 puppeteer-core 而非 puppeteer，前者不会下载额外的 Chromium。
Playwright 连接
使用 chromium.connectOverCDP() 方法：
const { chromium } = require('playwright');
const browser = await chromium.connectOverCDP('http://127.0.0.1:调试端口');
const context = browser.contexts()[0];
const page = context.pages()[0];Playwright 需要传入 HTTP 格式的调试地址，而非 WebSocket 格式。具体对接细节可参考Playwright 接管指纹浏览器的完整流程。
Selenium 连接
通过 ChromeOptions 的 debuggerAddress 参数接管：
from selenium import webdriver
from selenium.webdriver.chrome.options import Options
chrome_options = Options()
chrome_options.add_experimental_option("debuggerAddress", "127.0.0.1:调试端口")
driver = webdriver.Chrome(options=chrome_options)Selenium 不需要完整的 WebSocket 路径，只需要 IP 和端口。
连接成功后，自动化脚本可以像操作普通浏览器一样发送指令。此时浏览器使用的是指纹浏览器环境中预先配置的指纹参数与代理设置，Cookie 和本地存储也完全隔离。
任务完成后关闭环境
自动化任务执行完毕后，需要通过 Local API 提供的环境关闭接口（通常是另一个 HTTP 请求）释放浏览器进程。关闭接口会：
- 终止浏览器内核进程
- 回写当前会话的 Cookie 与缓存到环境存储
- 释放系统资源
如果不调用关闭接口直接结束脚本，浏览器窗口可能残留在后台，多次执行后会导致进程堆积、内存占用飙升。
关闭接口同样需要传入环境 ID 和鉴权凭证。部分工具支持批量关闭或强制终止。
何时选择 Local API
Local API 适合需要在本地环境精细控制浏览器行为的场景：
- 开发阶段调试自动化脚本，需要实时看到浏览器操作过程
- 小规模任务，单机资源足够支撑并发数
- 需要与其他本地工具（如 OCR、数据库）联动处理
如果要跨机器分布式执行、在无界面的服务器环境批量运行、或由云端统一调度，则需要评估远程 API 或容器化方案。
NexBrowser 在免费档已开放全功能 Local API 且不限调用次数，可以下载客户端安装后直接用于测试与小规模自动化。付费只增加窗口与成员容量，不改变 API 可用性。
再核对一遍流程
- 本地客户端保持登录，API 服务已启动
- 拿到目标环境的唯一 ID（不是名称或序号）
- 调用启动接口，传入环境 ID，拿到 CDP 调试地址
- 根据自动化工具选择对应的连接方法
- 任务结束后调用关闭接口释放进程
两个易踩坑的地方：环境 ID 与环境名称不是一回事，CDP 地址格式因工具而异。卡在启动环节时先确认 ID 正确、再排查环境是否被占用或代理是否可达。
评论(0)