企业官网建设流程全解析

• 测试
• 性能剖析
• 指标监控

Browsertime 是 sitespeed.io 的心脏：它驱动真实浏览器访问 URL（或执行脚本），运行内置 JavaScript 探针、录制浏览器视口视频、采集 HAR 与各类性能指标。本文基于官方文档 Browsertime 文档入口 及其 Introduction、Installation、Configuration、Details、Graphite 各子页面编写，并结合本仓库中的源码（browsertime 插件、CLI 选项定义 等）逐层展开，帮助你在 Docker 或 Node.js 环境下安装运行 Browsertime、完整理解其配置项与底层调用链，并将采集到的指标接入监控体系。

Browsertime 是什么：四大核心能力

Browsertime 的定位可以概括为一句话：驱动真实浏览器、运行你的 URL（或脚本）、收集性能数据。它既是 sitespeed.io 的测试引擎，也可以作为独立命令行工具或 JavaScript 库使用。从 Introduction 文档看，它具体做四件事：

1. 驱动浏览器：桌面端的 Chrome、Firefox、Edge 和 Safari，Android 上的 Chrome/Firefox，以及 iOS 上有限支持的 Safari；
2. 运行 JavaScript 探针：页面就绪后运行一组内置脚本，外加你自定义的任意脚本；
3. 录制浏览器视口视频：用于计算 Visual Metrics（Speed Index、First Visual Change、Last Visual Change 等）；
4. 支持 Selenium 风格脚本：在导航前、中、后运行脚本——登录用户、点击走通一个流程、测量 SPA 路由切换等。

两种常见使用方式：

• 作为独立的命令行工具，收集某个页面或某条用户旅程的性能指标；
• 作为你自己工具内部的 JavaScript runner，启动浏览器、运行你的代码并返回结果。

一次完整运行的流程如下（源自 Introduction 文档的逐步描述）：

1. 你给 Browsertime 一个 URL（或脚本）以及配置；
2. Browsertime 通过 WebDriver 协议（Selenium 及对应的 ChromeDriver / GeckoDriver / MSEdgeDriver / SafariDriver）启动浏览器；
3. FFmpeg 开始录制浏览器视口（开启 video 时）；
4. 浏览器导航到目标 URL；
5. 页面就绪后（“就绪”的判定由你决定），Browsertime 运行内置探针并收集：Navigation Timing / User Timing 条目、绘制时机（First Paint、First Contentful Paint）、Core Web Vitals（LCP、CLS、INP）、以及 Chrome trace 中的 Long Tasks 与 CPU 活动（--cpu）；
6. 录制 HAR 文件，包含页面全部请求与响应；SPA 路由切换也会通过 Chrome 的 soft-navigation entry type 被捕获；
7. FFmpeg 停止录制，视频被分析出 Speed Index 等 Visual Metrics。

最终产物是一个包含全部指标的 JSON 文件、一个 HAR 文件、一段视频和截图。

安装与第一次运行

文档给出两条安装路径（见 Installation）：Docker 镜像（最省事，镜像内置 Chrome、Firefox、Xvfb 以及视频录制和 Visual Metrics 所需的全部依赖）和Node.js 独立安装。

Docker 方式

官方镜像为sitespeedio/browsertime，容器启动时会自动为你拉起 Xvfb，你只需安装 Docker 并运行镜像。

Mac 与 Linux：

docker run --rm -v "$(pwd)":/browsertime sitespeedio/browsertime:28.0.0 --video --visualMetrics https://www.sitespeed.io/

Windows（Docker for Windows）：

C:\Users\Vicky> docker pull sitespeedio/browsertime C:\Users\Vicky> docker run --rm -v "$(pwd)":/browsertime sitespeedio/browsertime:28.0.0 https://www.sitespeed.io -b firefox

运行结果写入当前目录。注意文档模板中的版本号{% include version/browsertime.txt %}在本仓库中实际解析为 28.0.0；而本仓库作为 sitespeed.io 项目依赖的 browsertime 版本为28.3.0（见 package.json），两者均以 28.x 为基准。

独立安装（Node.js）

前置条件：

• Node.js 20 或更高（如果要用 TypeScript 编写的导航脚本，需要 22.18+）；Linux 上可用 nvm 管理版本；
• npm（随 Node.js 附带）或 yarn；
• 本地安装好的 Chrome 和/或 Firefox。

# npm npm install browsertime -g # yarn yarn global add browsertime

Windows 平台官方仅通过 Docker 支持，文档明确说明原生 Windows 支持需要核心贡献者投入维护。

最简单的一次运行

使用 Docker 镜像（自带 Chrome、Firefox、Xvfb 与视频依赖）：

docker run --rm -v "$(pwd)":/browsertime sitespeedio/browsertime:28.0.0 --video --visualMetrics https://www.sitespeed.io/

或使用 Node.js 安装：

browsertime https://www.sitespeed.io

这会用 Chrome 加载https://www.sitespeed.io/一次，并把带时序数据的 JSON 文件（browsertime.json）和 HAR 文件（browsertime.har）写入browsertime-results/www.sitespeed.io/$date/目录。加-n 3即可让同一 URL 测试 3 次（每次迭代之间浏览器会重启）。

核心配置选项

Browsertime 高度可配置。运行docker run sitespeedio/browsertime --help可列出全部选项，官方文档给出的选项清单（见 Configuration，原文内嵌 config.md）如下：

browsertime.js [options] <url>/<scriptFile> connectivity -c, --connectivity.profile 网络配置文件 [choices: "4g", "3g", "3gfast", "3gslow", "3gem", "2g", "cable", "native", "custom"] [default: "native"] --connectivity.engine 连通性引擎。throttle 适用于 Mac 与基于 tc 的 Linux；移动端在有 Humble 环境时可用 humble；如果网络限制在 Browsertime 外部完成则用 external [choices: "external", "throttle", "humble"] [default: "external"] Options: --cpu 便捷开关：Chrome 上同时启用 chrome.timeline，Firefox 上启用 geckoProfile [boolean] --video 录制并保存视频。设为 false 可移除因 visualMetrics 产生的视频；要彻底关闭录制需把 video 与 visualMetrics 都设为 false。需要安装 FFMpeg [boolean] --visualMetrics 收集 First Visual Change、SpeedIndex、Perceptual Speed Index、Last Visual Change 等 Visual Metrics。需要 FFMpeg 与 Python 依赖 [boolean] -b, --browser 指定浏览器。Safari 仅限 OS X/iOS，Edge 仅限支持 Edge 的系统 [choices: "chrome", "firefox", "edge", "safari"] [default: "chrome"] -n, --iterations 测试次数（每次测试之间重启浏览器） [number] [default: 3] --config JSON 配置文件路径。也可使用 .browsertime.json，会被 Browsertime 通过 find-up 自动发现 --resultDir 设置 Browsertime 产出文件的结果目录 --preURL, --warmLoad 浏览器先访问该 URL，再访问你要分析的 URL。用于填充浏览器缓存 --headless 以无头模式运行浏览器。支持 Firefox 与 Chrome [boolean] [default: false] -h, --help 显示帮助 -V, --version 显示版本号 Topics (use `browsertime --help <topic>`): timeouts, chrome, android, firefox, selenium, video, edge, safari, screenshot, pageload, proxy, connectivity, debug

用--help-all可看到所有细节选项。注意几个要点：

• -n每次迭代都重启浏览器，因此默认 3 次迭代得到的是可对比的多组样本，便于取中位数等统计量；
• --config与.browsertime.json：配置既可显式传 JSON 文件，也会被 find-up 机制向上搜索自动发现；
• --preURL：预热缓存的轻量方式，适合“带缓存二次访问”场景；
• topics 机制：完整选项按主题分组，browsertime --help chrome、--help video等可分主题查看。

sitespeed.io 侧的默认值与扩展选项

如果把 Browstime 作为 sitespeed.io 的引擎来驱动，本仓库的源码给出了更完整的参数全景。默认配置 中：

browser: 'chrome', // 默认浏览器 iterations: 3, // 默认 3 次迭代 connectivity: { profile: 'native', engine: 'external', ... }, screenshot: true, // 默认开启截图 screenshotLCP: true, // 针对 LCP 元素的截图 screenshotLS: true, // 针对 Layout Shift 的截图 viewPort: '1366x708', // 默认视口 xvfbParams: { display: 99 } // Xvfb 显示编号

lib/cli/options/browser.js 还暴露了文档 CLI 列表之外的大量进阶选项，摘选几组关键的：

视频与 Visual Metrics 侧的选项（lib/cli/options/video.js）包括：

• --browsertime.visualMetrics（别名speedIndex）：收集 SpeedIndex、First Visual Change、Last Visual Change 等，需要 FFMpeg 与 Python 依赖；
• --browsertime.visualMetricsPerceptual/--visualMetricsContentful：分别追加 Perceptual Speed Index 与 Contentful Speed Index；
• --browsertime.videoParams.framerate（默认 30）、--videoParams.crf（默认 23）、--videoParams.addTimer（默认 true，视频叠加计时器与指标标记）；
• filmstrip 相关：--videoParams.createFilmstrip（默认 true）、--videoParams.filmstripQuality（默认 75）、--videoParams.thumbsize（默认 400）、--videoParams.filmstripDiff（生成每帧差异图与视觉不稳定性热图）。

其中--videoParams.noiseTolerance是一个值得注意的细节参数：默认 0 表示沿用“允许 5 个像素差异”的旧行为；若观察到 Last Visual Change 明显偏晚但 filmstrip 中并无可见变化，文档建议尝试0.05——原因是浏览器可能在页面视觉稳定后仍会重栅格化，产生文字边缘的亚像素噪声，从而抬高 Last Visual Change、Speed Index 与 VisualComplete95/99。

视频与 Speed Index：最直观的产出

获取视频和 Speed Index 最简单的方式就是用官方 Docker 容器——它自带 VisualMetrics 所需的全部依赖。默认视频会叠加计时器（timer overlay）并标记各指标触发的时间点，加--videoRaw可关掉这些叠加层。

官方文档给出的视频示例：可见计时器叠加与指标标记。

本地构建与测试 Docker 镜像的流程（见 Details）：

# 在 browsertime 仓库中构建镜像 docker build -t sitespeedio/browsertime . # 运行一次测试 docker run --rm -v "$(pwd)":/browsertime-results sitespeedio/browsertime -n 1 --video --visualMetrics https://www.sitespeed.io/

网络限速（Connectivity）与移动端测试

网络限速

把网络限速可以让性能回归更容易被发现。文档推荐两种方式：搭建 Docker network bridge，或使用 Throttle 组件（参见 Throttle 文档 与 连通性完整指南）。对应 CLI 中--connectivity.profile的可选值（4g、3g、3gfast、3gslow、3gem、2g、cable、native、custom），以及--connectivity.engine的三种取值：

• throttle：在 Mac 与基于 tc 的 Linux 上生效；
• humble：移动端场景，需要自备 Humble 环境；
• external（默认）：网络限制在 Browsertime 之外完成，例如通过 Docker 网络。

真机移动端测试

Browsertime 支持 Android 上的 Chrome（Visual Metrics、HAR、视频）和 iOS 上的 Safari（通过ios_webkit_debug_proxy获取 HAR，macOS 下经 USB 支持视频与 Visual Metrics）。开始之前：

• 安装 ADB 并准备好手机（步骤见 移动端测试文档）；
• iOS 需要安装ios-webkit-debug-proxy（macOS 上brew install ios-webkit-debug-proxy）。

注意：移动端测试不支持 Docker 内运行，需要先在本地机器装好 VisualMetrics 依赖；若要在真机上做网络限速，可以使用 Pi Network Conditioner 之类的工具。

browsertime --android https://www.sitespeed.io --video --visualMetrics

源码级纵深：sitespeed.io 如何驱动 Browsertime

文档讲的是“Browsertime 能做什么”，本仓库的源码则回答了“sitespeed.io 是怎么用它”。以下结论均可在代码中核实：

1. 插件入口与默认配置合并。lib/plugins/browsertime/index.js 是 browsertime 插件的入口。open()方法中通过_merge({}, defaultConfig, options.browsertime)把 默认配置 与用户在 CLI/配置文件中传入的browsertime.*选项合并，随后向消息队列广播browsertime.setup，并注册三组指标过滤器：browsertime.pageSummary、browsertime.summary、browsertime.run（当limitedRunData开启时改用精简版指标集）——这决定了 HTML 报告与数据源各拿到什么粒度的指标。

2. 真正的测试执行在 analyzer 中。lib/plugins/browsertime/analyzer.js 从browsertimenpm 包导入BrowsertimeEngine与browserScripts，围绕它编排三种运行形态：

• 预热（preWarmServer）：preWarmServer()用独立参数（iterations: 1）新建一个BrowsertimeEngine，访问目标 URL 让服务器热身后关闭，并等待preWarmServerWaitTime（默认 5000ms）——对应 CLI 的--preWarmServer；
• 额外剖析轮（extraProfileRun）：extraProfileRun()单独跑一轮只做剖析，不采集常规指标。Chrome 下开启chrome.timeline、chrome.coverage及 V8 CPU profiler / blink.debug trace 类别；Firefox 下开启geckoProfiler与collectMozLog。这与 CLI 中--enableProfileRun的描述一致——用一次不计入测量的额外运行换取 trace/coverage 数据，避免每次迭代都付出剖析开销；
• 结果合并：mergeProfileCoverage()、mergeProfileModuleCosts()、mergeProfileFunctionCosts()等函数把剖析轮采到的 coverage、cpu.moduleCosts、cpu.functionCosts等以source: 'profileRun'标记合并回主结果，供 HTML 报告读取。从源码结构看，这套“主运行 + 剖析运行”双轨设计正是--enableProfileRun/--enableVideoRun选项在引擎层的落地。

3. 版本一致性。文档模板中的版本号 28.0.0 与 package.json 中声明的依赖browsertime: 28.3.0属同一 28.x 系列，本文所有命令与选项说明均以此版本区间为准；若你在其他版本上运行，个别选项（如noiseTolerance、filmstrip 相关参数）可能不存在，建议先执行browsertime --help-all核对。

把指标发送到 Graphite

如果你运行的是独立 Browsertime CLI（而不是 sitespeed.io），文档给出了一条基于jq与nc（netcat）的最简指标上报路径（见 Graphite 页面）。注意：若你运行的是 sitespeed.io，应改用其内置的 Graphite 集成（见 sitespeed.io 的 Graphite 文档），它自带 dashboard 与更丰富的配置。

第一步，运行 Browsertime 并把browsertime.json生成到tmp目录：

docker run --shm-size=1g --rm -v "$(pwd)":/browsertime-results sitespeedio/browsertime:28.0.0 --video --visualMetrics --resultDir tmp https://www.sitespeed.io/ -n 5

第二步，用jq从 JSON 中取出 5 次运行的 SpeedIndex 中位数，通过 netcat 发送到 Graphite 的 2003 端口：

echo "browsertime.your.key.SpeedIndex.median" $(cat tmp/browsertime.json | jq .statistics.visualMetrics.SpeedIndex.median) "`date +%s`" | nc -q0 my.graphite.com 2003

三个组成部分：browsertime.your.key.SpeedIndex.median是发给 Graphite 的 metric key 前缀；jq .statistics.visualMetrics.SpeedIndex.median负责从 JSON 中挑出中位数值；nc负责把数据送到你的 Graphite 服务器。

小结与延伸阅读

• 能做什么：驱动 5 类浏览器（桌面 Chrome/Firefox/Edge/Safari、Android Chrome/Firefox、iOS Safari）、跑内置+自定义 JS 探针、录视频算 Visual Metrics、执行 Selenium 风格脚本；
• 怎么装：Docker（推荐，依赖全内置）或 Node 20+ 下的npm install browsertime -g；
• 怎么跑：browsertime <url>，产物为browsertime.json+browsertime.har+ 视频 + 截图，默认 3 次迭代；
• 怎么调：--help快速选项 +--help <topic>分主题查看，--config/.browsertime.json承载复杂配置；
• 怎么接监控：jq + netcat 直推 Graphite，或走 sitespeed.io 内置集成。

延伸阅读（均为本仓库内文档）：Introduction、Installation、Configuration 与选项清单、Details、Graphite 上报。

• 测试
• 性能剖析
• 指标监控