drissionpage-dev

DrissionPage 开发

概述

使用此技能，参照一致的工作流并查阅 references/docs/ 中附带的官方文档，以使用 Python 构建可靠的 DrissionPage 自动化流程。

偏好

• 对于较长的“查询等待”流程，不要使用 DrissionPage 原生等待 API；而应轮询静态 HTML（tab.html / 快照），并使用 parsel.Selector（或等效的 HTML 解析器）检测状态转换。
• 当 DrissionPage 原生“就绪”检查不可靠时，不要依赖它们；而应解析静态 DOM，检查稳定的页面标记（例如主要内容已挂载、验证码/遮罩层已显示或已消失），以实现就绪检查。
• 在开发期间启动本地自动化浏览器时，默认使用 ChromiumOptions().auto_port(True)，这样 DrissionPage 会使用隔离的端口和用户数据目录启动全新的浏览器，而不会与默认的 127.0.0.1:9222 实例冲突。
• 如果任务需要连接到特定的现有浏览器、固定调试端口、可复用配置文件或由外部管理的浏览器进程，则不要启用 auto_port(True)；此时应明确配置 set_local_port()、set_address() 和 set_user_data_path()。
• 将 run_js(..., as_expr=True) 视为仅表达式模式：此模式下绝不要包含 return。如果脚本需要 return、控制流或多条语句，请改用默认的函数体模式。排查无法解释的轮询失败时，请优先检查这种模式不匹配，因为 DrissionPage 会在 as_expr=True 搭配 return 时抛出异常。
• 传入 run_js() / run_js_loaded() / run_async_js() 的参数只能是 DrissionPage 支持的基本类型。不要直接传入 Python list、dict、None、自定义对象或其他复杂值；请使用 json.dumps() 序列化复杂数据，并在 JavaScript 中用 JSON.parse() 解析；调用 run_js() 前，还应将 None 等可选值规范化为空字符串或其他明确的基本类型。

分阶段工作流

请先遵循此阶段门控流程，再参照下方的旧版工作流详情。

开发阶段

1. 明确自动化目标，并选择 SessionPage、ChromiumPage 或 WebPage。
2. 在编写交互代码之前，明确配置启动方式。
3. 从真实 DOM 或附带的文档中查找稳定的页面标记和选择器。
4. 首先实现最小且可靠的路径：导航、等待/就绪检查、定位、交互/提取、验证结果。
5. 仅在基本路径正常运行后，再添加下载、上传、网络监听、多标签页处理或备用轮询。
6. 让等待、重试、JavaScript 执行和异常处理过程可观察，不要悄然忽略页面状态错误。

检查阶段

交付前运行以下固定检查清单：

• 确认所选页面模式符合目标：仅 HTTP、浏览器渲染，或混合浏览器/会话行为。
• 确认浏览器启动使用 auto_port(True)，用于可丢弃的开发浏览器；除非必须连接到特定的受管浏览器。
• 确认定位器已根据真实 DOM 或附带的 DrissionPage 定位文档进行检查。
• 确认等待使用稳定的页面标记或明确的就绪条件，且较长的查询等待不依赖不可靠的原生就绪检查。
• 确认 run_js(..., as_expr=True) 中仅包含表达式形式的 JavaScript，且只接收受支持的基本类型参数。
• 确认轮询、重试、清理和备用路径中的异常处理范围明确，并记录了上下文信息。
• 确认脚本包含可运行的冒烟测试路径，用于验证一条端到端的自动化流程。

旧版工作流

1) 明确目标并选择模式

• 如果目标数据可通过 HTTP 响应获取，且不需要 JS 渲染，优先使用 SessionPage。
• 如果必须运行真正的 Chromium 浏览器（JS 渲染、复杂登录、反机器人流程、文件对话框等），优先使用 ChromiumPage。
• 如果需要在同一个对象中同时控制浏览器和发送/接收数据包（切换模式），优先使用 WebPage。

文档：

• references/docs/🌏 导入 - DrissionPage官网.md（核心类和导入路径）
• references/docs/⭐ 模式切换 - DrissionPage官网.md 和 references/docs/🗺️ 模式切换 - DrissionPage官网.md（模式切换）

2) 创建对象并配置启动

• 使用 ChromiumOptions 配置浏览器启动参数；请记住：选项仅在启动浏览器时生效，连接到现有浏览器时不会生效。
• 对于日常本地开发，优先先使用 auto_port(True)。这可以避免常见故障：DrissionPage 尝试访问 127.0.0.1:9222，却连接到非自动化 Chrome 或过期端口，进而引发 BrowserConnectError。
• 将浏览器启动模式视为一项明确的选择：
  • 在开发和调试期间使用 auto_port(True) 启动一个可随时丢弃的新浏览器。
  • 只有在有意重新连接到现有浏览器时，才使用固定端口或显式地址。
• 使用 SessionOptions 配置 SessionPage / WebPage 的 s 模式。
• 使用 Settings 配置全局行为（例如，未找到元素时是否抛出异常）。

文档：

• references/docs/🌏 导入 - DrissionPage官网.md
• references/docs/🛩️ 创建页面对象 - DrissionPage官网.md
• references/docs/🛩️ 启动配置 - DrissionPage官网.md
• references/docs/⚙️ 全局设置 - DrissionPage官网.md

3) 使用官方语法定位元素

• 以定位语法文档为准；不要猜测选择器格式。
• 重构时，集中管理定位器，并优先使用显式等待，而非休眠。

文档：

• references/docs/🔦 概述 - DrissionPage官网.md
• references/docs/🔦 定位语法 - DrissionPage官网.md
• references/docs/🔦 语法速查表 - DrissionPage官网.md
• references/docs/🔦 相对定位 - DrissionPage官网.md
• references/docs/🔦 在结果列表中筛选 - DrissionPage官网.md

4) 交互、等待并处理框架/标签页

• 使用专用等待 API 来提高稳定性；将超时视为需要优先处理的问题。
• 显式处理 iframe。
• 操作新窗口/标签页时，使用标签页管理 API。

文档：

• references/docs/🛰️ 元素交互 - DrissionPage官网.md
• references/docs/🛰️ 等待 - DrissionPage官网.md
• references/docs/🛰️ iframe 操作 - DrissionPage官网.md
• references/docs/🛰️ 标签页管理 - DrissionPage官网.md

5) 下载、上传和网络调试

• 下载时，使用文档介绍的 download / 浏览器下载流程。
• 上传时，参考上传文档，并优先采用稳定的文件选择方式。
• 调试不稳定的流程时，使用截图/录像、控制台日志和网络监听。

文档：

• references/docs/⭐ 下载文件 - DrissionPage官网.md
• references/docs/⤵️ download方法 - DrissionPage官网.md
• references/docs/⤵️ 浏览器下载 - DrissionPage官网.md
• references/docs/🛰️ 上传文件 - DrissionPage官网.md
• references/docs/🛰️ 截图和录像 - DrissionPage官网.md
• references/docs/🛰️ 获取控制台信息 - DrissionPage官网.md
• references/docs/🛰️ 监听网络数据 - DrissionPage官网.md

6) 异常和故障排查

• 有针对性地捕获并处理 DrissionPage 异常；不要一概捕获所有异常。
• 在 run_js() 周围进行轮询或等待时，不要默默吞掉可能掩盖脚本结构错误或页面状态错误的异常。记录异常上下文或缩小异常类型范围，以便 as_expr=True 与 return 等组合造成的错误能立即显现。
• 如果 run_js() 报告不支持某种参数类型（例如不支持 list 或 NoneType），请修改调用方，使其仅传递基本类型；对于选择器数组，传入 json.dumps(selectors)，并在脚本中使用 JSON.parse(arguments[0])。
• 如果实际行为与预期不符，请查阅常见问题。

文档：

• references/docs/⚙️ 异常的使用 - DrissionPage官网.md
• references/docs/❓ 常见问题 - DrissionPage官网.md

快速搜索示例（适用于 Codex）

• 按关键词搜索打包的文档：

  • rg -n -S "<keyword>" references/docs
  • 搜索不区分大小写的英文术语：rg -n -i "<keyword>" references/docs

• 知道 API 名称时，按标识符搜索：

  • rg -n -S "\\bChromiumPage\\b" references/docs
  • rg -n -S "\\bSessionPage\\b" references/docs

最简入门代码片段

请以文档中的参数和返回值为准。

from DrissionPage import ChromiumPage, WebPage, SessionPage
from DrissionPage import ChromiumOptions, SessionOptions
from DrissionPage.common import Settings

co = ChromiumOptions()
co.auto_port(True)  # Default for local development: isolated port + user data dir

page = ChromiumPage(addr_or_opts=co)