bitbrowser

v1.0.1

Published

2 months ago

比特浏览器 SDK - 用于控制和管理比特浏览器窗口的 TypeScript/JavaScript SDK

0High
0Medium
0Low

yfcoder

bitbrowser browser automation sdk fingerprint proxy anti-detect

BitBrowser SDK

比特浏览器 SDK - 用于控制和管理比特浏览器窗口的 TypeScript/JavaScript SDK

中文文档 | English Document

中文文档

简介

BitBrowser SDK 是一个基于 TypeScript/JavaScript 的比特浏览器自动化控制库。它提供了一套完整的 API 来创建、管理、控制比特浏览器窗口，支持指纹配置、代理管理、Cookie 操作等功能。

功能特性

✨ 核心功能

🌐 浏览器窗口的创建、打开、关闭、删除
👆 批量操作窗口
🔧 指纹配置和随机生成
🌍 代理配置和检测
🍪 Cookie 管理（获取、设置、清除）
📊 窗口布局和排列
🏷️ 窗口分组管理
💾 缓存管理

安装

npm install bitbrowser

或者使用 yarn:

yarn add bitbrowser

或者使用 pnpm:

pnpm add bitbrowser

快速开始

基础使用

import { BitBrowser } from "bitbrowser";

// 创建实例
const bitbrowser = new BitBrowser("http://127.0.0.1:54345");

// 健康检查
const isHealthy = await bitbrowser.health();
console.log("连接状态:", isHealthy ? "正常" : "失败");

// 创建浏览器窗口
const createResult = await bitbrowser.browser.create({
  name: "My Browser",
  proxyMethod: 2,
  proxyType: "socks5",
  host: "1.2.3.4",
  port: 1080,
  browserFingerPrint: {
    coreVersion: "130",
    ostype: "PC",
    os: "Win32",
  },
});

if (createResult.success) {
  const browserId = createResult.data.id;

  // 打开浏览器窗口
  const openResult = await bitbrowser.browser.open({
    id: browserId,
    queue: true,
  });

  console.log("WebSocket:", openResult.data?.ws);
  console.log("HTTP:", openResult.data?.http);
  console.log("PID:", openResult.data?.pid);
}

主要 API

窗口管理

| 方法 | 说明 | | --------------------- | ---------------- | | create(options) | 创建浏览器窗口 | | open(options) | 打开浏览器窗口 | | close(id) | 关闭浏览器窗口 | | delete(id) | 删除浏览器窗口 | | deleteMultiple(ids) | 批量删除窗口 | | getDetail(id) | 获取窗口详情 | | list(options) | 分页获取窗口列表 |

指纹管理

| 方法 | 说明 | | ------------------------------ | ------------ | | randomFingerprint(browserId) | 随机生成指纹 | | updatePartial(ids, options) | 修改指纹字段 |

代理管理

| 方法 | 说明 | | -------------------------- | -------------- | | updateProxy(ids, config) | 批量修改代理 | | check(options) | 检测代理可用性 |

Cookie 管理

| 方法 | 说明 | | ------------------------------ | ---------------------- | | get(browserId) | 获取窗口的实时 Cookies | | set(browserId, cookies) | 设置 Cookies | | clear(browserId, saveSynced) | 清除 Cookies |

窗口布局

| 方法 | 说明 | | ---------------------------- | ------------------ | | setBounds(options) | 排列窗口和调整尺寸 | | setFlexableBounds(seqlist) | 自适应排列窗口 |

其他功能

| 方法 | 说明 | | ------------------ | ---------------- | | getAllDisplays() | 获取所有显示器 | | getPids(ids) | 获取窗口 PID | | getAllPids() | 获取所有窗口 PID | | clear(ids) | 清理缓存 |

完整示例

单个窗口的完整工作流

import { BitBrowser } from "bitbrowser";

async function main() {
  const bitbrowser = new BitBrowser();

  try {
    // 1. 创建窗口
    const createResult = await bitbrowser.browser.create({
      name: "Test Browser",
      proxyMethod: 2,
      proxyType: "socks5",
      host: "1.2.3.4",
      port: 1080,
      proxyUserName: "user",
      proxyPassword: "pass",
      browserFingerPrint: {
        coreVersion: "130",
        ostype: "PC",
        os: "Win32",
        osVersion: "11",
      },
    });

    if (!createResult.success) {
      console.error("创建失败:", createResult.msg);
      return;
    }

    const browserId = createResult.data.id;
    console.log("✓ 窗口创建成功:", browserId);

    // 2. 打开窗口
    const openResult = await bitbrowser.browser.open({
      id: browserId,
      queue: true,
    });

    if (!openResult.success) {
      console.error("打开失败:", openResult.msg);
      return;
    }

    console.log("✓ 窗口已打开");
    console.log("  - PID:", openResult.data?.pid);
    console.log("  - WebSocket:", openResult.data?.ws);

    // 3. 等待一段时间后获取 Cookies
    await new Promise((resolve) => setTimeout(resolve, 5000));

    const cookiesResult = await bitbrowser.cookie.get(browserId);
    console.log("✓ Cookies 数量:", cookiesResult.data?.length || 0);

    // 4. 获取窗口详情
    const detailResult = await bitbrowser.browser.getDetail(browserId);
    console.log("✓ 窗口详情:", {
      id: detailResult.data.id,
      name: detailResult.data.name,
      status: detailResult.data.status,
    });

    // 5. 关闭窗口
    await bitbrowser.browser.close(browserId);
    console.log("✓ 窗口已关闭");

    // 6. 删除窗口
    await new Promise((resolve) => setTimeout(resolve, 3000));
    await bitbrowser.browser.delete(browserId);
    console.log("✓ 窗口已删除");
  } catch (error) {
    console.error("错误:", error);
  }
}

main();

批量操作示例

import { BitBrowser } from "bitbrowser";

async function batchOperations() {
  const bitbrowser = new BitBrowser();

  // 创建 5 个浏览器窗口
  const browserIds = [];
  for (let i = 0; i < 5; i++) {
    const result = await bitbrowser.browser.create({
      name: `Browser ${i + 1}`,
      proxyMethod: 2,
      proxyType: "noproxy",
      browserFingerPrint: {},
    });

    if (result.success) {
      browserIds.push(result.data.id);
    }
  }

  // 批量打开
  for (const id of browserIds) {
    await bitbrowser.browser.open({ id, queue: true });
  }

  // 批量排列
  await bitbrowser.window.setBounds({
    type: "box",
    width: 1000,
    height: 800,
    col: 2,
    spaceX: 10,
    spaceY: 10,
    ids: browserIds,
  });

  // 批量关闭
  for (const id of browserIds) {
    await bitbrowser.browser.close(id);
  }

  // 批量删除
  await bitbrowser.browser.deleteMultiple(browserIds);
}

batchOperations();

代理检测示例

import { BitBrowser } from "bitbrowser";

async function checkProxyExample() {
  const bitbrowser = new BitBrowser();

  const result = await bitbrowser.proxy.check({
    host: "1.2.3.4",
    port: 1080,
    proxyType: "socks5",
    proxyUserName: "user",
    proxyPassword: "pass",
    ipCheckService: "ip-api",
  });

  if (result.success && result.data.success) {
    console.log("IP:", result.data?.data.ip);
    console.log("国家:", result.data?.data.countryName);
    console.log("城市:", result.data?.data.city);
    console.log("时区:", result.data?.data.timeZone);
  } else {
    console.error("代理检测失败:", result.data.message);
  }
}

checkProxyExample();

类型定义

SDK 导出了所有的 TypeScript 类型，可以直接使用：

import {
  type ApiResponse,
  type BrowserFingerPrint,
  type CreateBrowserOptions,
  type OpenBrowserOptions,
  type OpenBrowserResult,
  type CheckProxyOptions,
  type CheckProxyResult,
  type Cookie,
} from "bitbrowser";

配置对象详解

BrowserFingerPrint (浏览器指纹配置)

coreProduct: 浏览器内核，默认 'chrome'
coreVersion: 内核版本，chrome 默认 130，firefox 默认 128
ostype: 操作系统平台 ('PC' | 'Android' | 'IOS')
os: navigator.platform 值
osVersion: 操作系统版本
userAgent: 自定义 UA
timeZone: 时区
webRTC: WebRTC 设置 ('0'=替换, '1'=允许, '2'=禁止, '3'=隐私)
position: 地理位置 ('0'=询问, '1'=允许, '2'=禁止)
languages: 语言列表
devicePixelRatio: 显示缩放比例
canvas: Canvas 指纹 ('0'=随机, '1'=关闭)
webGL: WebGL 图像 ('0'=随机, '1'=关闭)
更多配置项，详见官方文档

CreateBrowserOptions (创建窗口参数)

name: 窗口名称
url: 额外打开的 URL（逗号分隔）
browserFingerPrint: 指纹配置（必传）
proxyType: 代理类型 ('noproxy' | 'http' | 'https' | 'socks5' | 'ssh')
host: 代理主机
port: 代理端口
cookie: Cookie 字符串
syncTabs: 是否同步标签
syncCookies: 是否同步 Cookies
更多选项，详见类型定义

常见问题

Q: 如何连接到比特浏览器 Local Server？

A: 确保比特浏览器客户端已启动，Local Server 默认地址是 http://127.0.0.1:54345。如果 Local Server 使用了不同的端口，可以在创建时指定：

const bitbrowser = new BitBrowser("http://127.0.0.1:8888");

Q: 如何设置随机指纹？

A: 在创建窗口时传入空对象或部分配置，SDK 会自动生成随机值：

browserFingerPrint: {} // 完全随机
// 或者
browserFingerPrint: {
  ostype: 'PC', // 指定某些字段
  // 其他字段随机
}

Q: 支持并发打开多个窗口吗？

A: 支持，建议使用 queue: true 参数来防止并发问题：

for (const id of browserIds) {
  await bitbrowser.browser.open({ id, queue: true });
}

Q: 如何修改已存在的窗口指纹？

A: 使用 updatePartial() 方法：

await bitbrowser.browser.updatePartial([browserId], {
  browserFingerPrint: {
    timeZone: "Asia/Shanghai",
    languages: "zh-CN",
  },
});

API 参考

详细的 API 参考文档，请参考官方文档。

更新日志

1.0.0 (2026-01-19)

🎉 首个版本发布
完整的浏览器窗口管理 API
指纹配置和随机生成
代理管理和检测
Cookie 操作
窗口布局排列
完整的 TypeScript 类型支持

贡献

欢迎提交 Issue 和 Pull Request！

许可证

MIT License - 详见 LICENSE

English Document

Introduction

BitBrowser SDK is a TypeScript/JavaScript automation control library for BitBrowser. It provides a complete set of APIs to create, manage, and control BitBrowser windows, with support for fingerprint configuration, proxy management, cookie operations, and more.

Features

✨ Core Features

🌐 Create, open, close, and delete browser windows
👆 Batch window operations
🔧 Fingerprint configuration and random generation
🌍 Proxy configuration and detection
🍪 Cookie management (get, set, clear)
📊 Window layout and arrangement
🏷️ Window grouping management
💾 Cache management

Installation

npm install bitbrowser

Quick Start

import { BitBrowser } from "bitbrowser";

const bitbrowser = new BitBrowser("http://127.0.0.1:54345");

// Health check
const isHealthy = await bitbrowser.health();

// Create browser window
const result = await bitbrowser.browser.create({
  name: "My Browser",
  browserFingerPrint: {
    coreVersion: "130",
    ostype: "PC",
    os: "Win32",
  },
});

// Open browser
const openResult = await bitbrowser.browser.open({
  id: result.data.id,
  queue: true,
});

Documentation

For more examples and detailed API documentation, visit BitBrowser Official Documentation.

License

MIT License - see LICENSE for details.