幻影浏览器 - API创建配置详细文档

📋

概述

幻影浏览器提供了强大的 API 接口，允许开发者通过编程方式创建和管理浏览器配置。该 API 支持完整的指纹伪装、代理配置、以及多平台（Windows、Mac、Android、iPhone）的浏览器环境模拟。

✅智能默认值
所有参数都有合理默认值，最少只需提供 group_id

✅自动生成
指纹噪声值、设备信息、UA 等自动生成

✅参数覆盖
传入的参数会覆盖默认值

✅多平台支持
Windows、Mac、Android、iPhone

✅完整指纹
Canvas、WebGL、AudioContext 等全方位保护

🔑

认证方式

所有 API 请求需在请求头中携带您的 API 密钥进行身份验证：

Authorization: Bearer YOUR_API_KEY

在 幻影浏览器 → API管理 页面可获取或重置您的 API 密钥。请妥善保管，切勿泄露给第三方。

🔗

API 端点

基础 URL：http://127.0.0.1:{YOUR_PORT}/api（端口在 API & MCP → API端口配置中查看）

POST /api/browsers/profiles 创建浏览器配置（本文档重点介绍）

POST /api/browsers/launch/{id} 启动浏览器，返回调试端口（data.http）；支持 query 参数控制启动行为

DELETE /api/browsers/{id} 停止浏览器进程（返回 {"success":true}）

DELETE /api/browsers/profiles/{id} 删除浏览器配置（返回 {"code":200}，注意与其他接口格式不同）

GET /api/browsers/groups 获取分组列表（返回 msg.list[]，含 id 字段即 group_id）— 不知道分组 ID？可调用此接口查询，也可在幻影指纹浏览器「项目管理」页面直接查看分组旁的数字

🚀 /api/browsers/launch/{id} — Query 参数

参数名	类型	默认值	说明
`headless`	string	`"false"`	`"true"` = 无界面后台运行（速度快，省资源）；`"false"` = 显示窗口（调试时推荐）
`showCheckPage`	string	`"true"`	`"true"` = 启动时展示检测页面（可验证指纹/代理是否生效）；`"false"` = 跳过检测直接进入
`args`	string (JSON)	—	追加 Chrome 启动参数，JSON 数组字符串，如 `["--window-size=1280,720","--window-position=0,0"]`

🚨 调用启动接口前必须先确认：幻影浏览器主程序已打开并已登录账号！
幻影未运行时调用启动接口会立即失败（ConnectionError / 连接被拒绝）。
请先双击桌面图标打开幻影浏览器，登录后再运行脚本。

⚠️ 启动不了浏览器？检查 BASE_URL 的写法：
本文档示例 BASE_URL = "http://127.0.0.1:36108/api"（含 /api）。
若你的脚本只存端口号（如 PORT = "36108"），启动地址要写：
f"http://127.0.0.1:{PORT}/api/browsers/launch/{profile_id}"
关键：不要重复或遗漏 /api 路径。

# Python 启动示例（带窗口位置 + 关闭反检测标识）
import json
launch_params = {
    "headless":      "false",
    "showCheckPage": "true",
    "args": json.dumps([
        "--window-size=1280,720",
        "--window-position=0,0",
        "--disable-blink-features=AutomationControlled",
        "--exclude-switches=enable-automation",
        "--disable-dev-shm-usage"
    ])
}
response = requests.post(
    f"{BASE_URL}/browsers/launch/{profile_id}",
    # 若 BASE_URL 只是端口号，改成：
    # f"http://127.0.0.1:{PORT}/api/browsers/launch/{profile_id}",
    headers=HEADERS, params=launch_params, timeout=180
)

📦

请求参数详解

基本信息

参数	类型	必填	默认值	说明
`name`	string	否	自动化浏览器_时间戳	浏览器配置名称
`group_id`	number	必填	—	分组ID，必须提供
`remark`	string	否	自动化API创建的浏览器	备注信息

browser_config · 平台与 UA 配置

参数	类型	默认值	说明
`platform`	string	Windows 11	`Windows 10` / `Windows 11` / `Mac` / `Android` / `iPhone`
`ua`	string	自动生成	用户代理字符串，根据平台自动生成对应格式
`browserVersion`	string	自动生成	如 `Chrome 132.0.6831.123`，随机选择 131 或 132
`startPage`	string	""	启动页面 URL
`phoneBrand`	string	自动生成	Android 手机型号，如 `JLN_AL00`（仅 Android 平台）
`iphoneBrand`	string	自动生成	iPhone 型号，如 `iPhone 15 Pro Max`（仅 iPhone 平台）

browser_config · 指纹保护配置

参数	类型	默认值	说明
`canvas`	string	noise	`noise`（噪声）/ `real`（真实）
`canvasNoiseValue`	number	自动生成	canvas=noise 时自动生成
`webgpu`	string	noise	`noise` / `real`
`webgpuNoiseValue`	number	自动生成	webgpu=noise 时自动生成
`webgl`	string	noise	WebGL 指纹模式
`webglInfoMode`	string	custom	`custom` / `real`
`webglVendor`	string	自动生成	如 `Google Inc. (NVIDIA)`，根据平台自动选择
`webglRenderer`	string	自动生成	根据供应商自动选择
`clientRects`	string	noise	ClientRects 指纹
`clientRectsNoiseValue`	number	自动生成	clientRects=noise 时自动生成
`audioContext`	string	noise	AudioContext 指纹
`audioContextNoiseValue`	number	自动生成	audioContext=noise 时自动生成
`speechVoices`	string	noise	语音合成指纹
`fontFingerprint`	string	noise	字体指纹
`fontListMode`	string	default	字体列表模式
`fontList`	string	""	自定义字体列表（fontListMode=custom 时有效）
`ja4`	string	noise	JA4 指纹

browser_config · 硬件配置

参数	类型	默认值	说明
`screenResolution`	string	随机生成	如 `1920x1080`，从常见分辨率中随机选择
`colorDepth`	string	24	`24` / `32`
`hardwareConcurrency`	string	随机生成	CPU核心数：`4` / `8` / `12` / `16` / `32`
`deviceMemory`	string	随机生成	内存(GB)：`2` / `4` / `6` / `8` / `16`
`touchScreen`	string	disabled	`enabled` / `disabled`
`touchScreenValue`	number	3	最大触摸点数（touchScreen=enabled 时有效）

browser_config · 语言 / 时区 / 地理位置

参数	类型	默认值	说明
`languageMode`	string	ip	`ip`（根据IP自动）/ `custom`
`language`	string	en-US	languageMode=custom 时有效
`timezoneMode`	string	ip	`ip` / `custom`
`timezone`	string	America/Los_Angeles	timezoneMode=custom 时有效
`geolocation`	string	replace	`replace`（替换）/ `ask`（询问）/ `deny`（拒绝）

browser_config · 媒体设备 / WebRTC / 网络 / 系统伪装

参数	类型	默认值	说明
`mediaDevices`	string	noise	`noise` / `disabled`
`webrtc`	string	replace	`replace` / `real` / `disabled`
`networkInfoMode`	string	real	`real` / `custom`
`networkType`	string	4g	`wifi` / `4g` / `3g` / `ethernet`
`systemSpoofing`	string	enabled	`enabled` / `disabled`
`systemVersion`	string	自动生成	如 `11.0.22621`，根据平台自动生成
`hardwareModelName`	string	自动生成	如 `ASUS ROG Strix G15`
`deviceSerialNumber`	string	自动生成	7位随机序列号
`macAddress`	string	自动生成	随机 MAC 地址
`deviceName`	string	自动生成	如 `DESKTOP-AB12CDE`
`doNotTrack`	string	enabled	`enabled` / `disabled`
`bluetooth`	string	disabled	`enabled` / `disabled`
`portScanProtection`	string	enabled	`enabled` / `disabled`
`battery`	string	disabled	`enabled` / `disabled`

proxy_config · 代理配置

参数	类型	默认值	说明
`type`	string	Directly	`Directly` / `Http` / `Https` / `Socks5`
`proxyMode`	string	custom	`custom`（自定义）/ `platform`（平台代理）
`host`	string	""	代理主机地址
`port`	string	""	代理端口
`username`	string	""	代理用户名（可选）
`password`	string	""	代理密码（可选）
`platformProxyId`	string	""	平台代理ID（proxyMode=platform 时使用）

other_config · 其他配置

参数	类型	默认值	说明
`cloudSync`	boolean	true	云同步
`multiWindow`	boolean	false	多窗口模式
`blockImages`	boolean	false	阻止图片加载
`blockVideos`	boolean	false	阻止视频加载

📡

响应格式

✅ 创建配置成功响应

// POST /api/browsers/profiles
{
  "success": true,
  "data": {
    "id": 123,       // profile_id，后续启动/删除必用
    "name": "我的浏览器配置",
    "group_id": 1
  },
  "message": "配置创建成功"
}

✅ 启动浏览器成功响应

// POST /api/browsers/launch/{id}
{
  "success": true,
  "data": {
    "http": "http://127.0.0.1:9222",  // 调试地址，取最后端口号
    "ws":   "ws://127.0.0.1:9222/..."
  }
}

// Python 中提取端口：
debug_port = data["http"].split(":")[-1]  # → "9222"

✅ 获取分组成功响应

// GET /api/browsers/groups
{
  "code": 200,
  "msg": {
    "list": [
      { "id": 1, "name": "默认分组" },
      { "id": 2, "name": "测试分组" }
    ]
  }
}

❌ 失败响应

{
  "success": false,
  "error": "错误信息描述"
}

// 常见错误码：
// 401 → API Key 无效或未登录
// 404 → profile_id 不存在（已删除）
// 500 → 内部错误（检查日志）

⚠️ 特殊格式：删除配置接口

// DELETE /api/browsers/profiles/{id}
// 此接口返回 code 字段，而非 success 字段！
// Python 中需用 result.get('code') == 200 判断
{
  "code": 200,    // 200 = 成功，其他 = 失败
  "msg": "删除成功"
}

# Python 正确判断方式：
result = response.json()
if result.get('code') == 200:
    print("删除成功")
else:
    print(f"删除失败: {result.get('msg')}")

✅ 停止浏览器响应

// DELETE /api/browsers/{id}
{
  "success": true
}
// 404 = 进程已不存在（视为成功，无需处理）

💡

使用示例

仅提供必填参数，系统自动生成所有指纹、设备信息、UA等。

POST /api/browsers/profiles
{
  "group_id": 1
}

{
  "name": "Windows工作浏览器",
  "group_id": 1,
  "remark": "用于日常办公",
  "browser_config": {
    "platform": "Windows 11",
    "startPage": "https://www.google.com"
  },
  "proxy_config": {
    "type": "Http",
    "host": "proxy.example.com",
    "port": "8080",
    "username": "user",
    "password": "pass"
  }
}

{
  "name": "Mac测试浏览器",
  "group_id": 1,
  "browser_config": {
    "platform": "Mac",
    "startPage": "https://www.apple.com",
    "languageMode": "custom",
    "language": "zh-CN",
    "timezoneMode": "custom",
    "timezone": "Asia/Shanghai"
  }
}

phoneBrand 自动生成，如 JLN_AL00；UA 自动生成为 Android 格式。

{
  "name": "Android浏览器",
  "group_id": 1,
  "browser_config": {
    "platform": "Android"
  }
}

// 生成的UA示例：
// Mozilla/5.0 (Linux; Android 12; K) AppleWebKit/537.36 ...

{
  "name": "小米手机浏览器",
  "group_id": 1,
  "browser_config": {
    "platform": "Android",
    "phoneBrand": "M2011K2C"  // 手动指定小米手机型号
  }
}

iphoneBrand 自动生成，如 iPhone 15 Pro Max。

{
  "name": "iPhone浏览器",
  "group_id": 1,
  "browser_config": {
    "platform": "iPhone"
  }
}

// 生成的UA示例：
// Mozilla/5.0 (iPhone; CPU iPhone OS 15_3 ...) CriOS/132.0.6831.123 ...

{
  "name": "iPhone 14 Pro浏览器",
  "group_id": 1,
  "browser_config": {
    "platform": "iPhone",
    "iphoneBrand": "iPhone 14 Pro"
  }
}

{
  "name": "高级自定义浏览器",
  "group_id": 1,
  "browser_config": {
    "platform": "Windows 11",
    "canvas": "noise",
    "webgpu": "noise",
    "audioContext": "noise",
    "screenResolution": "2560x1440",
    "hardwareConcurrency": "16",
    "deviceMemory": "16",
    "languageMode": "custom",
    "language": "zh-CN",
    "timezoneMode": "custom",
    "timezone": "Asia/Shanghai",
    "webglVendor": "Google Inc. (NVIDIA)",
    "webglRenderer": "ANGLE (NVIDIA GeForce RTX 3070 ...)",
    "systemSpoofing": "enabled",
    "hardwareModelName": "ASUS ROG Strix G15",
    "webrtc": "replace"
  },
  "proxy_config": {
    "type": "Socks5",
    "host": "192.168.1.100",
    "port": "1080",
    "username": "proxyuser",
    "password": "proxypass"
  }
}

{
  "name": "使用平台代理的浏览器",
  "group_id": 1,
  "proxy_config": {
    "proxyMode": "platform",
    "platformProxyId": "proxy_123456"
  }
}

// JavaScript 批量创建示例
// 接口：POST /api/browsers/profiles
const BASE_URL = 'http://127.0.0.1:{YOUR_PORT}/api';
const HEADERS  = { 'Content-Type': 'application/json', 'Authorization': 'Bearer YOUR_API_KEY' };

const profiles = [
  { platform: "Windows 11", count: 10 },
  { platform: "Mac",        count: 5  },
  { platform: "Android",    count: 8  },
  { platform: "iPhone",     count: 7  }
];

for (const config of profiles) {
  for (let i = 0; i < config.count; i++) {
    const resp = await fetch(`${BASE_URL}/browsers/profiles`, {
      method: 'POST',
      headers: HEADERS,
      body: JSON.stringify({
        name: `${config.platform}_${i + 1}`,
        group_id: 1,
        browser_config: { platform: config.platform }
      })
    });
    const data = await resp.json();
    console.log(`创建成功，profile_id = ${data.data.id}`);
  }
}

🏆

最佳实践

📌 参数简化原则

只传入需要自定义的参数
其余使用系统默认值
避免传入大量默认参数

🖥️ 平台选择建议

Windows 11：通用，兼容性最佳
Mac：模拟苹果用户
Android：移动端/社交媒体
iPhone：iOS/高端用户模拟

🔐 高隐蔽性指纹（推荐）

canvas / webgpu / audioContext: noise
clientRects / speechVoices: noise
fontFingerprint: noise

🌐 代理选择建议

直连：测试/本地开发
HTTP/HTTPS：一般代理需求
SOCKS5：更好的隐私和性能
平台代理：幻影平台代理服务

📱 移动端配置技巧

touchScreen: enabled
networkType: 4g
Android 分辨率: 1080x2340
iPhone 分辨率: 1170x2532

❓

常见问题

Q1：为什么只需要提供 group_id？ ▼

系统为所有参数都设置了合理的默认值，并且会自动生成指纹噪声值、设备信息、UA 等。这样可以快速创建配置，同时保证每个配置都是唯一的。

Q2：Android 和 iPhone 平台会自动打开开发者工具吗？ ▼

是的，移动端平台（Android 和 iPhone）会自动添加 --auto-open-devtools-for-tabs 参数，启动时会自动打开开发者工具，方便调试。

Q3：手机型号是如何工作的？ ▼

Android：自动生成随机型号（如 JLN_AL00），添加到 navigator.phone_model
iPhone：自动生成型号（如 iPhone 15 Pro Max）
可手动指定 phoneBrand 或 iphoneBrand 覆盖自动值

Q4：WebGL 配置会根据平台自动调整吗？ ▼

Windows / Android：Google Inc. (Intel/AMD/NVIDIA)
Mac：Apple Inc. (Intel)
iPhone：Apple GPU

Q5：UA 字符串格式正确吗？ ▼

Windows：Mozilla/5.0 (Windows NT 10.0; Win64; x64) ...
Mac：Mozilla/5.0 (Macintosh; Intel Mac OS X ...) ...
Android：Mozilla/5.0 (Linux; Android 12; K) ... Mobile Safari/537.36
iPhone：Mozilla/5.0 (iPhone; CPU iPhone OS 15_3 ...) CriOS/... Mobile ...

Q6：如何测试创建的配置是否正确？ ▼

创建后使用启动 API：

// 启动浏览器（POST）
POST http://127.0.0.1:{YOUR_PORT}/api/browsers/launch/{profile_id}
Authorization: Bearer YOUR_API_KEY

// 成功后返回：
{ "success": true, "data": { "http": "http://127.0.0.1:9222" } }

// 用 DrissionPage 连接调试端口：
debug_port = data["http"].split(":")[-1]  # 取 "9222"

返回的 data.http 中提取端口号，可用于 DrissionPage / Selenium / Puppeteer 等工具连接。

Q7：配置创建失败怎么办？ ▼

group_id 未提供或不存在 → 检查分组 ID 是否正确
参数格式错误 → 检查 JSON 格式是否正确
端口未启动 → 确保应用程序正在运行

Q8：浏览器版本是 131 还是 132？ ▼

目前支持 Chrome 131 和 132 两个版本，系统会随机选择其中一个版本号，并添加随机的子版本号（0-200）。

Q9：创建或启动超时（ReadTimeout）怎么办？ ▼

创建配置超时（90秒）：通常是代理 IP 连通性太差或 API 服务器繁忙。检查代理是否可用、网络是否正常。
启动浏览器超时（180秒）：第一次启动会下载内核，耗时较长；或代理 IP 连接不稳定，Cookies/指纹服务器无响应。建议更换代理 IP 后重试。
超时后可直接重试，脚本会自动换代理和重新创建配置。
如大量超时，请检查：api_url 端口是否正确、幻影浏览器是否已登录。

Q10：为什么删除配置的响应格式和其他接口不同？ ▼

DELETE /api/browsers/profiles/{id} 返回的是 {"code": 200, "msg": "..."}，而其他大多数接口返回 {"success": true, "data": {...}}。

判断成功：result.get('code') == 200
判断失败：result.get('code') != 200，错误信息在 result.get('msg')
HTTP 404 表示配置不存在（已被删除），可视为成功，无需处理。

# 正确的判断方式：
resp = requests.delete(f"{BASE_URL}/browsers/profiles/{profile_id}", headers=HEADERS, timeout=60)
if resp.status_code == 404:
    print("配置已删除")
elif resp.status_code == 200:
    result = resp.json()
    if result.get('code') == 200:
        print("删除成功")
    else:
        print(f"删除失败: {result.get('msg')}")

🤖

自动化完整示例（Python + DrissionPage）

以下示例展示了从 创建配置 → 启动浏览器 → DrissionPage 连接 → 执行操作 → 清理 的完整流程，与官方脚本保持一致。

每一步都有详细说明，新手按顺序复制即可运行。

① 准备工作：获取分组 ID（group_id）

创建浏览器配置时必须填 group_id，不知道是多少？运行下面的代码查一下：

import requests

# ① 把端口号换成你的（在「API & MCP → API端口配置」中查看）
# ② 把 YOUR_API_KEY 换成你的（在「API管理」页面生成）
BASE_URL = "http://127.0.0.1:36108/api"
HEADERS  = {"Authorization": "Bearer YOUR_API_KEY"}

resp = requests.get(f"{BASE_URL}/browsers/groups", headers=HEADERS, timeout=5)
# 注意：分组列表接口返回格式是 resp.json()["msg"]["list"]，和其他接口不同
groups = resp.json()["msg"]["list"]
for g in groups:
    print(f"分组 ID = {g['id']}  名称 = {g['name']}")
# 输出示例：分组 ID = 1  名称 = 默认分组
# 把你需要的分组 ID 记下来，填到下面的 GROUP_ID

② 完整流程：创建 → 启动 → 连接 → 操作 → 清理

📦 Step 0：导入依赖 & 填写配置

在终端执行一次安装：pip install drissionpage requests

import requests, json
from DrissionPage import ChromiumPage, ChromiumOptions

# ════════ 只需修改这里 ════════
BASE_URL = "http://127.0.0.1:36108/api"  # 端口在「API & MCP → API端口配置」中查看
API_KEY  = "YOUR_API_KEY"               # ← 替换成你的 API Key
GROUP_ID = 1                             # ← 替换成你的分组 ID（方式一：幻影指纹浏览器「项目管理」分组旁边的数字；方式二：运行上面的代码从 API 获取）
# ═══════════════════════════════

# 请求头：每次请求都要带上，Authorization 用于身份验证
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

Step 1：创建浏览器配置

告诉幻影：用什么指纹和代理创建一个新浏览器，返回 profile_id

print("正在创建浏览器配置...")
r = requests.post(f"{BASE_URL}/browsers/profiles", headers=HEADERS, timeout=90, json={
    "group_id": GROUP_ID,
    "browser_config": {
        "platform":       "Windows 11",  # 平台：Windows 10/11 / Mac / Android / iPhone
        "canvas":         "noise",        # Canvas 指纹噪声（让每个窗口的指纹都唯一）
        "webgpu":         "noise",        # WebGPU 指纹噪声
        "audioContext":   "noise",        # 音频指纹噪声
        "clientRects":    "noise",        # ClientRects 指纹噪声
        "ja4":            "noise",        # JA4 指纹噪声
        "webrtc":         "replace",      # WebRTC 替换（防止泄露真实 IP）
        "systemSpoofing": "enabled"       # 系统伪装（伪装成真实 Windows 设备）
    },
    # 【代理配置】没有代理把整个 proxy_config 这段删掉即可
    "proxy_config": {
        "type":      "Http",    # 代理协议：Http / Https / Socks5 / Directly（直连）
        "proxyMode": "custom", # custom=自定义代理；platform=幻影平台代理
        "host":      "1.2.3.4", # 代理服务器 IP
        "port":      "8080",    # 代理端口
        "username":  "user",    # 无账号密码填空字符串 ""
        "password":  "pass"
    },
    "other_config": {
        "cloudSync":   True,   # 开启云同步（多设备同步数据）
        "blockImages": False,  # 是否屏蔽图片（True=加快加载速度，但页面图片不显示）
        "blockVideos": False   # 是否屏蔽视频
    }
})

# 判断是否成功，失败时打印错误信息
result = r.json()
if not result.get("success"):
    print(f"创建失败：{result.get('error')}")
    exit(1)

# 取出 profile_id，后续启动和删除都用它
profile_id = result["data"]["id"]
print(f"创建成功！profile_id = {profile_id}")

Step 2：启动浏览器

幻影会真正打开一个 Chrome 窗口，并返回调试端口（DrissionPage 需要用这个端口连接）

🚨 启动浏览器前必须先确认：幻影浏览器主程序已打开并已登录账号！
幻影未运行时调用启动接口会立即失败（ConnectionError）。请先双击桌面图标打开幻影浏览器，登录后再运行脚本。
同时确认 BASE_URL 端口号正确：在幻影「API & MCP → API端口配置」中查看，默认 36108。

⚠️ 启动不了浏览器？检查 BASE_URL 的写法：
本文档示例 BASE_URL = "http://127.0.0.1:36108/api"（含 /api）。
若你的脚本只存端口号（如 PORT = "36108"），启动地址要写：
f"http://127.0.0.1:{PORT}/api/browsers/launch/{profile_id}"
关键：不要重复或遗漏 /api 路径。

🚫 报错 invalid character '<' looking for beginning of value？
这说明服务器返回的是 HTML 页面（通常是 404 错误页），而不是 JSON，根本原因可能是：
1. HTTP方法错误：该接口只支持 POST 请求，使用 GET 请求会返回 HTML 错误页
2. 缺少认证头：未提供 Authorization: Bearer YOUR_API_KEY 头
3. 接口路径写错了：幻影浏览器的启动接口路径是 /api/browsers/launch/{id}
解决方案：
- 使用 POST 请求而不是 GET 请求
- 在请求头中添加 Authorization: Bearer YOUR_API_KEY
- 确保接口路径正确：/api/browsers/launch/{id}
常见错误写法（其他平台路径，不适用于幻影）：
  ❌ /api/browser/start/{id}（AdsPower 等其他浏览器的路径）
  ❌ /api/v1/browser/start
  ✅ /api/browsers/launch/{id}（幻影浏览器正确路径）
注意：browser（单数）和 browsers（复数）是两个不同的路径！

print("正在启动浏览器，请稍等...")
launch_params = {
    "headless":      "false",   # false=显示浏览器窗口（推荐调试时用）；true=无界面后台（省资源）
    "showCheckPage": "true",    # true=启动后展示指纹检测页（确认代理/指纹是否生效）
    "args": json.dumps([
        "--window-size=1280,720",                      # 窗口大小 1280×720
        "--window-position=0,0",                        # 窗口位置：左上角
        "--disable-blink-features=AutomationControlled", # 隐藏自动化特征（反检测）
        "--exclude-switches=enable-automation",          # 去掉自动化控制标识栏
        "--disable-dev-shm-usage"                        # 防止 Linux 共享内存不足崩溃
    ])
}
launch = requests.post(
    f"{BASE_URL}/browsers/launch/{profile_id}",
    headers=HEADERS, timeout=180,   # 首次启动需下载内核，耐心等待，不要改太短
    params=launch_params
)

launch_result = launch.json()
if not launch_result.get("success"):
    print(f"启动失败：{launch_result.get('error')}")
    exit(1)

# data.http 示例："http://127.0.0.1:9222"
# split(":")[-1] 取最后一段，得到端口号 "9222"
http_addr  = launch_result["data"]["http"]
debug_port = http_addr.split(":")[-1]   # → "9222"（DrissionPage 连接用）
ws_url     = launch_result["data"]["ws"]    # WebSocket 地址（Playwright/Puppeteer 用）
print(f"浏览器已启动！调试端口 = {debug_port}")

💡 附：多线程时自动排列窗口位置

同时运行多个浏览器时，通过 --window-size 和 --window-position 让每个窗口整齐排列，互不遮挡：

① 单个窗口（固定位置）

# 直接在 args 里设置窗口大小和位置
WIN_W = 500   # 窗口宽度（像素）
WIN_H = 500   # 窗口高度（像素）

args = [
    f"--window-size={WIN_W},{WIN_H}",  # 窗口大小
    "--window-position=0,0",          # 位置：从屏幕左上角(0,0)开始
    "--disable-blink-features=AutomationControlled",
    "--exclude-switches=enable-automation",
    "--disable-dev-shm-usage"
]

② 多线程自动排列（按屏幕宽高均匀分布）

import screeninfo   # 安装：pip install screeninfo

def calculate_window_positions(thread_count, win_w, win_h):
    """
    根据屏幕尺寸，自动计算每个窗口的摆放位置。
    规则：从左上角开始，先填满第一行，再填下一行（超出屏幕循环）。
    
    参数：
      thread_count: 窗口数量（线程数）
      win_w:        每个窗口的宽度（px）
      win_h:        每个窗口的高度（px）
    返回：
      positions: [{'x': 0, 'y': 0}, {'x': 500, 'y': 0}, ...]
    """
    screens = screeninfo.get_monitors()

    if not screens:
        # 获取屏幕信息失败时，简单错开排列
        return [{'x': i * 100, 'y': i * 50} for i in range(thread_count)]

    screen   = screens[0]          # 取主显示器
    screen_w = screen.width       # 例：1920
    screen_h = screen.height      # 例：1080

    # 计算每行能放几个、能放几行
    cols = max(1, int(screen_w / win_w))  # 例：1920/500 = 3 列
    rows = max(1, int(screen_h / win_h))  # 例：1080/500 = 2 行

    positions = []
    for i in range(thread_count):
        col = i % cols              # 第几列（0, 1, 2, 0, 1, ...）
        row = (i // cols) % rows   # 第几行（超出屏幕高度则从第0行循环）
        positions.append({'x': col * win_w, 'y': row * win_h})
    return positions

# 示例：5 个窗口，500×500，屏幕 1920×1080 → cols=3, rows=2
# 排列结果：
#   窗口0 (0,0)      窗口1 (500,0)    窗口2 (1000,0)
#   窗口3 (0,500)    窗口4 (500,500)

positions = calculate_window_positions(thread_count=5, win_w=500, win_h=500)

# 启动第 i 个浏览器时，把对应的位置传进去
for i, pos in enumerate(positions):
    args = [
        f"--window-size={WIN_W},{WIN_H}",
        f"--window-position={pos['x']},{pos['y']}",
        "--disable-blink-features=AutomationControlled",
        "--exclude-switches=enable-automation",
        "--disable-dev-shm-usage"
    ]
    # 然后把 args 传入 launch_params["args"] = json.dumps(args)

Step 3：DrissionPage 连接浏览器

用 Step 2 获取的端口号，让 DrissionPage 接管幻影已打开的浏览器：

# ChromiumOptions 用来告诉 DrissionPage：去连接哪个端口的浏览器
# set_local_port(debug_port) 指定端口号（就是上面 split(":")[-1] 得到的）
co = ChromiumOptions()
co.set_local_port(debug_port)   # 例：9222

# ChromiumPage 接管浏览器（不会新建，会连接已存在的）
page = ChromiumPage(addr_or_opts=co)
print("DrissionPage 连接成功！")

Step 4：执行业务操作

连接成功后，用 DrissionPage 的 API 控制浏览器做任何你想做的事：

# page.get() 等同于在地址栏输入 URL 并回车，会等待页面加载完再继续
page.get("https://www.baidu.com")
# page.title 是属性（不加括号），直接获取当前页面的 <title>
print(f"页面标题：{page.title}")

# ╔══════════════════════════════════════╗
# ║  在这里替换成你自己的业务逻辑          ║
# ║  例如：page.ele('input').input('内容') ║
# ╚══════════════════════════════════════╝

# ↓↓↓ 在这里写你的具体业务逻辑 ↓↓↓

# ↑↑↑ 在这里写你的具体业务逻辑 ↑↑↑

Step 5：清理（停止浏览器 + 删除配置）

任务完成后必须清理，否则会占用内存和磁盘。顺序不能反：先停进程，再删配置

# page.quit() 关闭 DrissionPage 的连接（不删除幻影配置）
page.quit()

# 停止浏览器进程（关闭 Chrome 窗口，释放 CPU 和内存）
requests.delete(f"{BASE_URL}/browsers/{profile_id}", headers=HEADERS, timeout=15)
# 删除浏览器配置数据（从幻影中移除这条记录，释放磁盘空间）
requests.delete(f"{BASE_URL}/browsers/profiles/{profile_id}", headers=HEADERS, timeout=60)
print("清理完成！")

③ 代理文件格式说明（批量脚本代理池）

如果你用文本文件存代理列表，每行一条，按以下格式：

# 格式：IP:端口:用户名:密码（冒号分隔，必须 4 段）
# 有账号密码的代理：
1.2.3.4:8080:user1:pass1
5.6.7.8:3128:user2:pass2
# 没有账号密码的代理（用户名和密码留空，但冒号保留）：
9.10.11.12:7890::

# 脚本中解析代理（每行拆成4段）：
proxy_parts = proxy.strip().split(":")
if len(proxy_parts) != 4:
    print(f"代理格式错误：{proxy}（应为 IP:端口:用户名:密码）")
    continue   # 跳过格式错误的行
host, port, username, password = proxy_parts

# 填入 proxy_config：
"proxy_config": {
    "type":     "Http",   # 根据你的代理类型填：Http / Socks5 / Directly
    "proxyMode": "custom",
    "host":     host,
    "port":     port,
    "username": username,  # 无认证时为空字符串 ""（不是 None）
    "password": password
}

📝

更新日志

v1.0.0 2025-01-08

支持多平台（Windows、Mac、Android、iPhone）
自动生成完整指纹配置
支持移动端手机型号配置
移动端自动开启开发者工具
智能默认值系统

文档版本：v1.0.0 · 最后更新：2025-10-05 · 适用版本：幻影浏览器 v1.0.0+

幻影浏览器 · API 创建配置详细文档

概述