使用 --bot-dpr 设置设备像素比策略
为 BotBrowser 会话选择 profile、real 或 advanced 显示缩放，并在桌面、移动端和 per-context 工作流中保持 DPR 一致。
BotBrowser Team
设备像素比策略属于显示决策，而不是渲染细节：Retina MacBook 的 window.devicePixelRatio 是 2，普通办公笔记本通常是 1 或 1.25，为一台设备准备的配置文件不该悄悄继承另一台的值。BotBrowser 用 --bot-dpr 的 profile、real 与 advanced 三种模式把这个数字的来源写进启动命令，而页面自身的响应式 CSS 以及站点如何使用所报告的值仍由网站决定。
关于不同的生命周期信号，请参阅活动窗口仿真与页面可见性状态。
TL;DR
--bot-dpr=profile是默认值：使用配置文件的显示缩放，同时设置--bot-window=profile和--bot-screen=profile时，DPR、窗口和屏幕可以一起保持一致。--bot-dpr=real跟随宿主机显示器，适合支持坐席或设计评审等以工作站屏幕为预期体验的场景。advanced保留配置文件 DPR 并做有限布局调整；它是实验性的，默认不启用，也不是更高精度的模式。- 要在 BrowserContext 创建第一个页面或 Worker 之前选定模式，因为已存在的页面会保持其 context 启动时的行为。
- 每次运行记录五个字段：BotBrowser 版本、配置文件、DPR 模式、视口和截图目标。
目录
观看视频
这段英文视频围绕一个数字 window.devicePixelRatio 展开。它先讲文章里的常见取值和三种模式（profile、real 与 advanced），再让真实浏览器回答自己的数字从哪里来：在 Ubuntu runner 的 stock Chrome 的 DevTools Console 中读取本地实验页（DPR 为 1，屏幕 1920×984，2dppx 查询不匹配）；Windows runner 的录像里 DevTools 界面从 1.25 缩放到 1.75，这是工具自身的缩放，不是页面的。最后讲 per-context 规则，以及每次运行都要记录的五个字段。录像中没有加载 BotBrowser 配置文件，所以 --bot-dpr 的各模式只是引用本文，并未实际运行。音频为英文。
显示缩放为什么对页面重要
window.devicePixelRatio 告诉页面一个 CSS 像素背后对应多少个物理像素。普通办公笔记本通常是 1 或 1.25，Retina MacBook 是 2，很多手机是 3。同一个值还会参与 CSS 分辨率媒体查询、响应式图片选择和布局计算，因此它与屏幕尺寸、窗口尺寸和色深一起构成显示配置。
当配置文件描述的是一块显示器，而宿主机的显示器是另一块时，同一个会话里就同时存在两套显示配置。--bot-dpr 选项让这个选择变成显式配置，而不是由浏览器恰好运行在哪台机器上来决定。BotBrowser 可以在受控上下文中为配置显式指定设备像素比，但不能改变站点如何对待这个值。
在普通浏览器里，这个值并不总是恒定的。MDN 指出，用户缩放页面时它会变化，在许多桌面环境中，窗口移动到缩放比例不同的显示器时它也会变化。页面可以通过分辨率媒体查询监听这些变化，所以应用可能在值更新后重新绘制图片或画布。对于可重复的工作流，这一点很实际：会话使用一个固定且有文档说明的显示缩放来源，页面就得到稳定的初始值，之后各次运行之间出现差异时，原因指向页面或宿主机，而不是某个没有记录的显示设置。
页面不会孤立地读取 DPR。CSS 分辨率查询可以在缩放变化时选择另一份样式表。响应式图片可以选择另一个来源。画布尺寸、可视视口计算和应用自带的缩放控件也可能取决于 CSS 像素与物理像素之间的关系。
移动端配置文件通常使用比桌面端更大的 DPR。重点不是数字越大越好，而是该值要与预期的设备族一致，并与同一配置文件提供的屏幕尺寸一致。不要仅仅为了让页面使用更高分辨率的图片，就把手机的 DPR 复制到桌面配置文件里。
三种模式：profile、real 与 advanced
| 模式 | 适用场景 | 结果 |
|---|---|---|
profile | 由配置文件定义显示配置 | 使用配置文件的显示缩放。默认值。 |
real | 会话应跟随宿主机显示器 | 使用宿主机的显示缩放。 |
advanced | 现有工作流需要有限的布局调整，同时保留配置文件 DPR | 实验性兼容模式。默认不启用。 |
profile 是默认值，因此现有启动命令的行为保持不变。只有部署确实需要时才设置其他模式。
先从配置文件要代表的显示模型出发。基于配置文件的浏览器通常带有目标操作系统、视口族、屏幕尺寸和输入能力，显示缩放属于同一组数据。如果配置文件代表的是笔记本或手机，profile 能让缩放值与配置文件的其余数据保持关联。
当物理显示器本身就是用户体验的一部分时，使用 real，例如支持人员的工作站、设计评审，或必须遵循宿主机无障碍设置的浏览器会话。在这些情况下，宿主机显示器是事实来源。real 会暴露宿主机的显示缩放，它可能与所选配置文件不同，所以只有在这种基于宿主机的配置是有意为之时才选择它。
advanced 是实验性的，默认不启用。它保留配置文件的 DPR 并应用有限的布局调整，但不会重新缩放整个页面，也不保证布局测量值或截图一致。它不是精度更高的模式，宿主机与配置文件的 DPR 不同本身也不是启用它的理由。采用前，先在目标宿主机上检查受影响的页面布局和截图，如果调整带来不一致，就回到 profile。
桌面系统可能运行在缩放设置各不相同的显示器上。宿主机可能报告一个值，而配置文件是按另一个值准备的。当配置文件需要在不同机器之间保持稳定时，profile 很有用。当当前工作站必须决定显示行为时，real 很有用。两者都是有效选择，只是事实来源不同。
让 DPR 与窗口和屏幕保持一致
DPR、窗口和屏幕共同构成一套显示配置。要一起修改，不要在多次运行之间逐个调整。
chromium-browser \
--bot-profile="/path/to/profile.enc" \
--bot-dpr=profile \
--bot-window=profile \
--bot-screen=profile
桌面有头会话默认使用宿主机的窗口和屏幕尺寸。如果有头会话必须报告配置文件中的尺寸，请在 --bot-dpr=profile 旁边同时设置 --bot-window=profile 和 --bot-screen=profile。屏幕和窗口指南介绍了尺寸相关选项，设备模拟介绍了移动端配置文件。
代表操作者自己显示器的工作站会话，则可以让这三个值都使用宿主机显示器：
chromium-browser \
--bot-profile="/path/to/profile.enc" \
--bot-dpr=real \
--bot-window=real \
--bot-screen=real
具体的窗口和屏幕取值取决于配置文件和部署。这两个示例展示了三项策略之间的关系。请选择已安装的 BotBrowser 版本支持的取值，并让参与对比的页面使用同一组设置。
无头部署同样需要这种规范。没有可见显示器时，显示来源仍然是一个需要做出的选择：决定会话代表配置文件的显示，还是宿主机的显示，并显式写出选项，而不是继承机器碰巧提供的值。
当会话在本地工作站和远程机器之间迁移时，要决定浏览器代表的是操作者的显示，还是配置文件的目标显示，并让这个决定成为部署配置的一部分。避免根据会在不同机器之间悄悄变化的环境变量来选择模式。可见的启动参数更便于审计最终行为。使用 real 的本地测试在没有物理显示器的机器上可能得到不同结果，使用 profile 的测试也可能与绑定显示器的工作站测试不同。两种结果都没有错，但差异必须是有意为之。
Per-context 会话
使用 per-context 指纹时，要在 BrowserContext 创建第一个页面或 worker 之前设置 --bot-dpr。所选策略会一直与该 context 的显示和布局行为关联。已有页面保留其 context 启动时确立的行为，因此之后修改启动命令不会更新它们。当显示配置必须改变时，关闭并重新创建 context。
当主浏览器和 per-context 配置文件代表同一台设备时，使用相同的模式。只有当 context 有意代表不同的显示环境时，才选择不同的模式。扩展浏览器上下文介绍了更完整的 context 生命周期。
如果多个 context 代表同一设备族，请使用相同的 DPR 策略，并配合一致的窗口和屏幕设置。如果它们有意代表不同设备，就把每个 context 的设置一起保存在各自的配置记录里。当应用依赖稳定的响应式布局时，不要让同一个 context 在基于配置文件的显示和基于宿主机的显示之间共用。
context 池也应记录所选的模式。这有助于解释为什么两个 URL 相同的页面会收到不同的响应式标记，也能防止 worker 继承为另一种显示策略创建的 context。
启动大量 context 的服务，应在共享的启动配置中设置该模式，并把它复制到每个 context 的创建选项里。启动时记录所选模式，但不要记录配置文件内容。让一个负责人维护封装脚本和启动服务使用的命令行默认值。如果多个脚本各自选择默认值，一次维护改动就可能把 context 池拆成不同的显示策略。
封装脚本构造命令行时，应把所选模式作为完整的值传入，而不是拼接未经验证的文本。只接受 profile、real 和 advanced，并在启动浏览器之前拒绝其他任何值。启动失败比会话悄悄使用另一种显示策略更容易诊断。
验证并记录策略
- 使用选定的配置文件和一种 DPR 模式启动会话。
- 整个检查过程中保持窗口、屏幕和 DPR 不变。
- 使用相同的配置文件和模式启动第二个会话，确认显示行为一致。
- 对比不同模式时，只修改
--bot-dpr，并记录每次运行的完整启动命令。
验证浏览器指纹列出了可以查看所报告显示值的公开检测工具。
| 情况 | 操作 |
|---|---|
| 期望使用配置文件的显示行为 | --bot-dpr=profile |
| 会话必须跟随宿主机显示器 | --bot-dpr=real |
| 现有工作流需要布局调整 | 在目标宿主机上评估实验性的 --bot-dpr=advanced，否则保持 profile |
| 不同 context 之间显示不一致 | 在每个 context 创建页面或 worker 之前设置模式 |
| 有头模式的尺寸跟随了宿主机 | 添加 --bot-window=profile 和 --bot-screen=profile |
完整的选项说明见 CLI 选项参考。
为每次运行保留一份简短记录。能解释大多数显示缩放差异的字段有五个：BotBrowser 版本、配置文件、DPR 模式、视口和采集目标，例如截图、PDF 或页面测量值。有了这五个字段，审阅者无需重新打开页面，就能判断两次采集的差异来自策略、配置文件，还是输出的生成方式。
要在同一页面上对比模式，请用相同的浏览器版本、配置文件、视口、窗口模式和屏幕模式把同一流程运行三遍，两次运行之间只修改 --bot-dpr。把启动命令与每个结果保存在一起。如果两次运行有差异，保存的命令会立刻显示模式是否是唯一的改动；如果没有差异，说明该流程不依赖显示缩放。
截图尺寸以 CSS 像素表示，而输出的位图可能受设备缩放因子影响。对比图像的测试应在参考采集和当前采集中保持 DPR 模式固定。否则，布局可能没有变化，而位图尺寸或文字栅格化却不同。
PDF 和打印流程有自己的页面尺寸规则，但为打印提供内容的网页布局仍然取决于视口和显示取值。请在加载文档之前选定 DPR 策略，并把打印设置与显示设置分开。这样更容易区分 CSS 布局变化和纸张尺寸变化。
做视觉回归时，把策略与视口、浏览器版本一起写入测试元数据。只有预期的显示策略发生变化时才重新生成基线。不要仅仅因为某个运行器的显示器不同就更新截图。可移植的基线使用 profile，明确绑定某台工作站的测试使用 real。
交付配置之前，请在启动记录中确认以下几点：
- BotBrowser 版本已固定；
- 配置文件目标和宿主机角色已有文档说明；
- DPR 模式是显式的；
- 窗口和屏幕模式是显式的；
- 模式在创建第一个页面之前设置；
- 截图或响应式测试使用与其基线相同的策略；
- 每个 per-context 配置都记录自己的显示策略；
- 从
profile改为real或advanced，按行为变更来评审。
这些检查不需要页面暴露配置文件的私有数据，却能让运营浏览器的团队清楚看到显示行为的来源。如果部署之后布局出现差异，启动记录会告诉你最先该对比哪些地方。
推广与维护策略
先从一个有代表性的配置文件和一个应用流程开始。用 profile 运行该流程，然后在相同的浏览器版本、视口和窗口设置下重复一次。如果宿主机显示器是需求的一部分，再用 real 重复对比。把每次运行的输出与启动记录保存在一起。这样在把策略应用到更大的池之前，团队就有了一小组参考结果。
先把所选模式推广到一组 context。检查使用响应式导航、图片选择、表格、图表和打印布局的页面，因为这些区域往往比普通文本页面更早显现显示变化。如果结果合适，再把同样的配置应用到代表同一设备族的其余 context。
把所选模式当作测试输入的一部分，而不是环境细节。当缺陷报告说页面看起来不一样时，第一个问题就是会话使用了哪种显示来源。如果启动记录能回答这个问题，排查就可以直接转向页面、配置文件或宿主机。
不要把策略变更与浏览器版本变更、配置文件迁移或视口改版混在一起。每一种变更都可能改变布局行为。需要多项变更时，请分别在单独的测试运行中应用，并分开保存记录。清晰的顺序能让你判断是哪一项变更影响了结果。
升级到新的 BotBrowser 版本后，即使命令行没有变化，也要重新检查所选策略。默认值仍然是 profile，但新版本可能改变可用的文档或支持的选项。用相同的配置文件和采集设置做升级前后的对比。如果结果发生变化，按以下顺序检查：浏览器版本、配置文件、窗口模式、屏幕模式和 DPR 模式。
把浏览器版本、配置文件、所选模式、视口和采集目标保存在测试或服务配置旁边。当页面改变响应式布局、图片来源发生变化，或截图以意外的尺寸渲染时，这份记录很有用。它也为审阅者提供了一份在推广之前需要批准的具体取值清单。
宿主机的显示设置可能影响有头工作站上的文字大小、对比度和输入行为。如果操作者直接使用浏览器，real 可能更符合这个人对显示的预期。如果浏览器是基于配置文件的可移植会话，profile 能在宿主机变化时保持显示行为稳定。请与实际使用该会话的人讨论这个选择，而不是只根据服务器默认值来选模式，并使用与生产环境相同的视口和窗口设置进行无障碍评审。
最常见的错误有三个：在更换宿主机时让模式保持隐式，在 context 已经创建页面之后才修改 DPR，以及把 advanced 当作通用的质量设置。当工作流依赖这三项显示策略时，请显式写出它们，为新的显示策略创建新的 context，并把 advanced 限定在确实需要它的工作流中。
显示策略放在启动配置旁边时最容易维护。请把所选模式写进部署说明、测试夹具和运维手册，让同事不必打开页面，就能知道会话是跟随配置文件还是跟随宿主机。当配置从开发环境转到生产环境时，保留模式以及相关的窗口和屏幕设置，并且每当部署改变模式时，都把旧模式、新模式与更新后的视觉基线一起记录下来。
BotBrowser 提供 --bot-dpr 选项来选择设备像素比策略（默认是 profile，real 对应宿主机显示器，另有实验性的 advanced）。在 context 创建第一个页面之前设置它，桌面会话和 per-context 会话就能保持同一个有文档说明的显示缩放来源，团队因此可以只改这一个选项来对比各次运行。BotBrowser 不能让 advanced 重新缩放整个页面，也不保证布局测量值或截图一致，更不控制宿主机显示器、页面自身的响应式 CSS，以及网站如何使用所报告的值。
像素比在没有 resize 事件时也可能改变，处理方式见移动端视口变化事件指南。
公开来源
实践结论
把 --bot-dpr 当作测试输入的一部分：可移植基线用 profile，只有工作站显示器本身就是需求时才用 real，advanced 应在目标宿主机上评估而不是当作默认值。之后为每次运行保留一条启动记录，写明 BotBrowser 版本、配置文件、模式、视口和截图目标，这样截图或响应式布局差异会指向页面，而不是某个没有记录的显示设置。
本文属于指南： 什么是浏览器指纹？原理、风险、信号与隐私边界