官网文档：https://www.drissionpage.cn/browser_control/browser_options
一、核心对象与初始化
1. 类定义
-
作用：管理Chromium内核浏览器的启动配置，仅在浏览器启动时生效。
-
导入方式 ：
pythonfrom DrissionPage import ChromiumOptions
2. 初始化参数
| 参数名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
read_file |
bool | True |
是否从ini文件读取配置（False则使用默认配置） |
ini_path |
str/Path | None |
指定ini文件路径（None时读取内置配置文件） |
3. 创建示例
python
# 从ini文件读取配置（默认）
co = ChromiumOptions()
# 使用默认配置（不读取ini文件）
co = ChromiumOptions(read_file=False)二、启动参数与命令行设置
1. 基础参数操作
| 方法名 | 作用 | 参数说明 |
|---|---|---|
set_argument(arg, value=None) |
添加启动参数（如--headless） |
arg：参数名；value：参数值（无值参数传None，删除参数传False） |
remove_argument(arg) |
删除指定启动参数 | arg：参数名（无需值） |
clear_arguments() |
清空所有启动参数 | 无参数 |
2. 常用预设参数
| 方法名 | 作用 | 参数类型 | 默认值 | 示例 |
|---|---|---|---|---|
headless(on_off=True) |
设置无头模式 | bool | True |
co.headless(True) |
incognito(on_off=True) |
设置无痕模式 | bool | True |
co.incognito() |
ignore_certificate_errors(on_off=True) |
忽略证书错误 | bool | True |
co.ignore_certificate_errors() |
no_imgs(on_off=True) |
禁用图片加载 | bool | True |
co.no_imgs(True) |
no_js(on_off=True) |
禁用JavaScript | bool | True |
co.no_js(True) |
mute(on_off=True) |
静音模式 | bool | True |
co.mute(True) |
三、路径与端口配置
1. 路径设置
| 方法名 | 作用 | 参数说明 |
|---|---|---|
set_browser_path(path) |
设置浏览器可执行文件路径 | path：文件路径（字符串/Path对象） |
set_user_data_path(path) |
设置用户数据目录（配置文件） | path：目录路径 |
use_system_user_path(on_off=True) |
使用系统默认用户目录 | on_off：是否启用（默认True） |
set_tmp_path(path) |
设置临时文件目录 | path：目录路径 |
set_cache_path(path) |
设置缓存目录 | path：目录路径 |
set_download_path(path) |
设置下载文件路径 | path：目录路径 |
set_paths(**kwargs) |
批量设置路径 | 支持参数：browser_path, user_data_path, download_path等 |
2. 端口与地址
| 方法名 | 作用 | 参数说明 |
|---|---|---|
set_local_port(port) |
手动设置本地端口 | port：端口号（整数/字符串） |
set_address(address) |
设置连接地址（格式ip:port） |
address：地址字符串（如127.0.0.1:9222） |
auto_port(on_off=True, scope=None) |
自动分配端口（多线程适用） | on_off：是否启用；scope：端口范围元组（如(5000, 6000)，左闭右开） |
注意：
set_local_port()、set_address()与auto_port()互斥，后调用的方法生效。- 多进程需通过
scope指定端口范围避免冲突。
四、插件与用户配置
1. 插件管理
| 方法名 | 作用 | 参数说明 |
|---|---|---|
add_extension(path) |
添加插件（支持解压目录或.crx） | path：插件路径 |
remove_extensions() |
移除所有已添加的插件 | 无参数 |
existing_only(on_off=True) |
仅操作已存在的插件（防报错） | on_off：是否启用（默认True） |
2. 用户与偏好设置
| 方法名 | 作用 | 参数说明 |
|---|---|---|
set_user(user='Default') |
设置用户配置文件夹名称 | user：文件夹名（如'Profile 1'） |
set_pref(arg, value) |
设置浏览器偏好配置 | arg：配置项名称；value：配置值（如'profile.default_content_settings.popups': 0） |
remove_pref(arg) |
删除内存中的偏好配置 | arg：配置项名称 |
remove_pref_from_file(arg) |
删除配置文件中的偏好配置 | arg：配置项名称 |
clear_prefs() |
清空所有偏好配置 | 无参数 |
五、运行时与网络配置
1. 超时与重试
| 方法名 | 作用 | 参数说明 |
|---|---|---|
set_timeouts(base=None, page_load=None, script=None) |
设置超时时间（秒） | base：默认超时；page_load：页面加载超时；script：JS运行超时 |
set_retry(times=None, interval=None) |
设置连接重试策略 | times：重试次数；interval：重试间隔（秒） |
2. 网络与加载策略
| 方法名 | 作用 | 参数说明 |
|---|---|---|
set_load_mode(mode='normal') |
设置加载模式（提高效率） | mode：'normal'（默认）、'eager'（DOM就绪）、'none'（仅连接） |
set_proxy(proxy) |
设置浏览器代理（单次生效） | proxy：代理字符串（如'http://localhost:1080'，不支持带认证代理） |
set_user_agent(user_agent) |
设置用户代理字符串 | user_agent：完整UA文本（如'Mozilla/5.0 (Windows)...'） |
六、实验性配置（Chrome Flags）
| 方法名 | 作用 | 参数说明 |
|---|---|---|
set_flag(flag, value=None) |
设置Chrome实验性参数（chrome://flags） |
flag：参数名；value：参数值（无值参数不传） |
clear_flags() |
清空内存中的实验性参数 | 无参数 |
clear_flags_in_file() |
清空配置文件中的实验性参数 | 无参数 |
七、状态保存与属性
1. 配置保存
| 方法名 | 作用 | 参数说明 |
|---|---|---|
save(path=None) |
保存配置到ini文件 | path：文件路径（None时保存到当前读取的文件） |
save_to_default() |
保存到内置ini文件 | 无参数 |
2. 只读属性（获取当前配置）
| 属性名 | 类型 | 说明 |
|---|---|---|
address |
str | 浏览器连接地址（格式ip:port） |
browser_path |
str | 浏览器可执行文件路径 |
user_data_path |
str | 用户数据目录路径 |
timeouts |
dict | 超时设置（base, page_load, script） |
arguments |
list | 启动参数列表 |
extensions |
list | 插件路径列表 |
关键使用规则
- 配置生效时机 ：所有设置需在浏览器启动前完成（通过
Chromium(co)传递配置对象）。 - 互斥方法 ：
- 端口相关：
set_local_port()/set_address()与auto_port()互斥，后调用优先。 - 路径相关：
set_user_data_path()与auto_port()互斥（自动分配路径会覆盖手动设置）。
- 端口相关：
- 多进程限制 ：
auto_port()不支持多进程，需通过scope参数为每个进程分配独立端口范围。 - 插件兼容性 ：推荐使用解压后的插件目录，而非
.crx文件（稳定性更高）。