为自定义 Chromium 构建配置 Playwright MCP

Playwright MCP 服务器位于代理客户端与浏览器之间，实际启动哪一个浏览器由一项容易被忽略的配置决定。配置正确时，代理驱动选定的构建与 profile。配置错误时，服务器启动自带的 Chromium 并报告成功，代理可能在一个并非预期的浏览器上完成整个任务。配置键承载自定义可执行文件，回读证明哪个二进制已启动，profile 参数则存在被静默丢弃的故障模式。Playwright MCP 是 Microsoft 的项目，有独立发布周期，配置项对应其公开 schema。BotBrowser 支持从任何 Playwright 兼容启动器传入 executablePath 与 profile 参数，并且不能提供自己的 MCP 服务器，因此无法修正一个从不转发该选项的服务器。

TL;DR

• 可执行文件的位置是 browser.launchOptions.executablePath，顶层键无效。MCP 配置 schema 把 Playwright 的 LaunchOptions 嵌套在 browser 下，未知顶层键会被忽略，而不是被拒绝。
• 另外两条途径更容易出错：--executable-path CLI flag 与 PLAYWRIGHT_MCP_EXECUTABLE_PATH 环境变量。每个部署只有一条途径，避免过期值胜出。
• profile flag 位于 launchOptions.args 的独立数组元素，因为 Playwright 会把每个元素作为单独参数传递。
• 会话内部的三项证明是 navigator.userAgent、服务器报告的进程路径，以及自定义构建暴露的页面级标记。回退到自带 Chromium 的服务器会在这三项上给出不同答案。
• 每个 profile 对应一个 MCP 服务器实例。持久 profile 锁定到单个浏览器实例，两个客户端共享工作区时会冲突，而不是相互隔离。

目录

• 可执行文件路径应放在哪里
• 传递 profile 而不丢失它
• 确认实际启动的二进制
• 故障模式与回退分支
• 实践结论

可执行文件路径应放在哪里

MCP 配置文件是一个包含 browser 对象的 JSON 文档。该对象内的 launchOptions 类型为 Playwright 的 LaunchOptions，与直接 Playwright 脚本传给 browserType.launch 的类型相同。executablePath 位于此处，服务器只读取这一层嵌套。

{
  "browser": {
    "browserName": "chromium",
    "launchOptions": {
      "executablePath": "/opt/botbrowser/chrome",
      "headless": true,
      "args": ["--bot-profile=/etc/botbrowser/profile.enc"]
    },
    "contextOptions": {
      "viewport": { "width": 1280, "height": 800 }
    }
  }
}

该配置块中有三个属性的重要性高于其余部分。browserName 保持 chromium，因为自定义 Chromium 构建仍使用 Chromium 协议，firefox 或 webkit 会路由到不同驱动。headless 位于 launchOptions，不在 browserName 旁边，因为服务器会把整个对象转发给启动调用。args 是独立字符串组成的数组，每个元素成为一个参数；包含空格的单个字符串不会被拆分。

途径	值的写入位置	覆盖对象	常见错误
配置文件	browser.launchOptions.executablePath	无其他来源，除非同时设置 flag 或环境变量	把 executablePath 写在文件顶层
CLI flag	--executable-path /path/to/chrome	配置文件	认为该 flag 同时设置 browserName
环境变量	PLAYWRIGHT_MCP_EXECUTABLE_PATH=/path/to/chrome	配置文件	从 shell profile 继承到过期值

三条途径是替代关系，不是叠加层。同时设置配置文件并导出环境变量的部署拥有两个事实来源，服务器最后读取哪一个，哪一个就决定浏览器。每个部署只有一条途径，启动环境中另外两条保持未设置。

未知键为何静默失败

服务器校验它认识的形状，忽略不认识的内容。把 executablePath 放在顶层、拼成 executable_path，或嵌套到 contextOptions 而非 launchOptions 下，都会得到正常启动的服务器和一个并非预期的浏览器。启动日志不一定说明这一点，因为从服务器视角配置有效，启动也已成功。

该行为使启动后的回读成为必要步骤。把成功启动当作预期二进制的证据，是最容易被忽略的失败方式，而且失败方向关键：代理工作、任务完成、浏览器错误。

context options 是独立对象

contextOptions 是另一个对象，承载 BrowserContextOptions 而非 LaunchOptions。视口尺寸、locale、时区、配色方案和权限属于该对象。把 executablePath 移入 contextOptions 会产生被忽略的无效 context 选项，浏览器回退到自带构建。

在扁平 JSON 文件中两个对象看似可互换，路径形状的值落入 contextOptions 即产生静默回退。启动前的回读比较 browser.launchOptions.executablePath 与磁盘上存在且可执行的字符串，并确认 browser.contextOptions 不包含任何路径形状的值。

三条途径的优先级

多条途径同时设置路径时，结果取决于服务器最后读取哪一条，该顺序由服务器实现决定。安全模式让另外两条无法生效：启动服务器的环境中 PLAYWRIGHT_MCP_EXECUTABLE_PATH 为空，配置文件已带该值时命令行不带 --executable-path。

启动环境中的具体检查只需一条命令：打印该变量并确认其为空，然后启动服务器。为无关项目导出该变量的 shell profile 常导致服务器在配置文件正确的情况下仍启动自带浏览器，因为环境变量覆盖值在读取配置文件之后合并，所以继承值优先。

同一推理适用于组装命令行的 wrapper 脚本。如果 wrapper 从一个在某些环境中为空的变量追加 --executable-path，该 flag 可能被完全丢弃，配置文件成为唯一来源。这是期望结果；wrapper 省略该 flag，而不是传入空值。

传递 profile 而不丢失它

profile 不是 Playwright 已知的启动选项。它是浏览器参数，因此在 launchOptions.args 中作为独立数组元素传递。直接 Playwright 脚本也以相同方式写入，所以把可用脚本转换为 MCP 配置时，profile 是最常丢失的部分。

{
  "browser": {
    "browserName": "chromium",
    "launchOptions": {
      "executablePath": "/opt/botbrowser/chrome",
      "args": ["--bot-profile=/etc/botbrowser/profile.enc", "--bot-locale=en-US"]
    }
  }
}

每个参数是一个数组元素，不带外层 shell 引号。"--bot-profile=/etc/botbrowser/profile.enc" 与 "--bot-profile=/etc/botbrowser/profile.enc --bot-locale=en-US" 并不等价：后者是一个含空格的参数，浏览器收到的是一个畸形 flag，而不是两个 flag。

profile 从何处读取

profile 文件必须能被服务器生成的进程读取，而该进程不总是操作者启动的进程。由桌面客户端启动的服务器继承客户端环境；容器内的服务器只能看到已挂载内容。交互式 shell 中有效的路径可能在 MCP 启动中失败，故障还可能表现为浏览器以默认值启动，而不是报错。

绝对路径在启动服务器的同一环境中解析一次，并记录在配置旁边。相对路径按服务器工作目录解析，该目录由客户端选择，操作者很少有意设置。

一个服务器实例，一个 profile

持久 profile 一次只能由一个浏览器实例使用。两个 MCP 客户端指向同一 profile，或一个客户端与一个手工浏览器会话共享同一 user data 目录，都会冲突：其中一个要么启动失败，要么接入另一个的状态。隔离开关通过把 profile 保存在内存中改变这一点，但关闭时丢弃 profile，因此它是不同模式，不是修复。

意图	设置	后果
一个客户端，一个固定 profile	持久 profile 加一个服务器实例	profile 锁定到该实例
多个客户端并行	隔离模式，或每个客户端独立 user data 目录	无共享状态；profile 不跨重启保留
复用已运行的浏览器	连接现有端点	服务器完全不启动配置的可执行文件

第三行是自定义构建部署中的陷阱。连接现有端点完全跳过启动路径，配置中的 executablePath 永远不会被读取。团队为提高启动速度加入 CDP 端点后，可能在不改任何启动选项的情况下静默失去自定义构建。

profile 状态与重启丢失的内容

持久 profile 与隔离 profile 的差别不只是存储。持久 profile 携带 cookie、local storage 和站点用于识别回访者的缓存状态。隔离 profile 在浏览器每次关闭时干净启动，依赖已登录会话的任务必须显式注入该状态，而不能假定它保留。

对监控或测试负载，这是正确权衡，因为干净启动让两次运行可比。对必须保持登录的负载，持久 profile 必需，单实例限制成为运行约束而非麻烦。在 profile 路径旁记录运行使用的模式，可避免后续把隔离运行与持久运行的比较误当作行为差异。

确认实际启动的二进制

唯一可靠的检查在代理驱动的会话内部执行。三个读数合在一起区分预期构建与自带回退，且每项成本都低。

第一项是 user agent 字符串。自定义构建报告的 Chromium 版本可能与自带构建不同，也可能报告一个不对应任何构建的已配置 user agent，因此这一读取只作佐证，不能作定论；自带构建报告的是随已安装 Playwright 包发布的版本，单次 navigator.userAgent 读取即可看到差异。

第二项是进程报告的可执行文件路径。构建向页面暴露该值时从页面读取；未暴露时，在生成服务器的主机上读取进程列表。两种方式得到的值都必须与配置路径逐字符相等。

第三项是自定义构建设置而原版构建没有的标记。它可以是浏览器 API 对象上的额外属性、产品专属命名空间中的版本字符串，或有文档记录的能力 flag。标记是三项中最强的证据，因为偶然相似的版本号无法产生它。

读数	预期构建的答案	自带回退的答案	读取位置
navigator.userAgent	自定义构建的 Chromium 版本	Playwright 自带版本	会话中的任意页面
进程可执行文件路径	配置的路径	Playwright 缓存下的路径	服务器进程列表，或构建暴露时的页面读取
自定义构建标记	存在	缺失或默认值	读取特定属性的页面脚本

只检查第一项的弱回读不够，因为自定义构建可能与自带构建共享版本字符串。只检查第三项也不够，因为它证明能力，不证明提供页面的进程身份。路径与标记都要检查，user agent 用作佐证。

代理可自行执行的回读

检查不需要单独 harness。客户端在会话中求值一个短表达式并返回结果，代理可直接与配置路径比较，无需离开对话。关键在于比较明确且被记录，自动化与否次之。

每次会话的三个记录值包括配置路径、观测路径和标记结果。路径匹配且标记存在的会话是预期构建。路径不匹配的会话是回退，无论 user agent 说什么。

构建未暴露路径时的读取方式

并非每个构建都向页面脚本暴露自身可执行文件路径，不暴露不是缺陷。页面无法回答时，匹配服务器子进程的父子关系是关键：一台机器可能运行多个 Chromium 进程，重要的是 MCP 服务器的后代进程，而不是手工打开的浏览器。

页面级标记仍是最低成本的正向信号，因此稳定属性来自构建供应方的确认，而不是对偶然属性的抓取。随小版本变化的标记比没有标记更差，因为它产生看起来像回退的假阴性。

故障模式与回退分支

故障聚成小集合，每个都有独特签名。命名后，诊断成为查表，而不是实验。

症状	原因	确认	修复
浏览器启动，user agent 版本错误	executablePath 未被读取	键位于顶层或 contextOptions 下	移入 browser.launchOptions
浏览器启动，profile 设置缺失	profile flag 被丢弃或畸形	args 中是一个含空格的字符串，而非独立元素	每个 flag 拆成一个数组元素
服务器以启动错误退出	配置路径缺失或不可执行	路径在服务器环境中无法解析	生成进程可读的绝对路径
第二个客户端无法启动浏览器	持久 profile 已被锁定	两个客户端指向同一 user data 目录	隔离模式，或每个客户端独立目录
启动加速后自定义构建被忽略	配置了现有端点	配置仍列有端点	端点移除后启动路径执行

前两行会产生在错误浏览器上工作的代理，启动日志也不会报告。其余三行失败得足够明显，是问题中成本较低的一半。

客户端能看到与不能看到的内容

MCP 客户端看到服务器暴露的工具：导航、快照、点击、输入，以及服务器发布的其他工具。它看不到启动配置、生成的进程或传入的参数。这种不对称使回读必须通过会话请求，而不能从客户端侧假定。

代理循环与浏览器进程之间的职责划分见面向 AI Agent 的 headless 浏览器，这份配置需要复现的直接脚本见Playwright 入门指南，基于 Puppeteer 的服务器所要求的扁平启动对象形状见Puppeteer MCP 服务器配置。这也解释了客户端为何无法自行检测回退。从客户端视角，服务器工作正常，事实也是如此：服务器启动了浏览器，并针对它提供工具。唯一知道预期浏览器的是编写配置的操作者。

记录验证结果

未写下的验证会被重复。配置路径、观测路径、标记结果和时间戳存放在同一记录中，后续会话可比较，而无需重新推导当时的“正确”含义。配置变化时，存储记录使变化可见，而不是静默发生。

这是直接 Playwright 启动也需要的纪律；在 MCP 服务器下更重要，因为启动离编写选项的人又远了一层。客户端看不到该层，记录是该层按预期配置的唯一持久证据。

FAQ

Playwright MCP 会读取配置文件顶层的 executablePath 吗？

不会。schema 把 Playwright 的 LaunchOptions 嵌套在 browser.launchOptions 下，顶层键不属于该形状。服务器忽略不认识的内容，因此位置错误的键会得到自带浏览器的正常启动，而不是校验错误。

一个 MCP 服务器能同时服务多个 profile 吗？

不能通过单个持久 profile 实现。持久 profile 锁定到一个浏览器实例，并行客户端需要隔离模式或独立 user data 目录。隔离模式把 profile 保存在内存中，关闭时丢弃，这是另一种权衡，不是共享同一 profile 的方式。

匹配的 user agent 足以证明启动了正确构建吗？

不能。自定义构建可能报告与自带构建相同的 Chromium 版本，版本匹配只能佐证，不能证明。进程可执行文件路径与配置路径的比较，加上只有自定义构建暴露的标记，才构成启动正确构建的证据。

实践结论

可执行文件的位置是 browser.launchOptions.executablePath，每个 profile 与 locale flag 各占一个 args 元素，路径来源只有三条途径中的一条。任何实际工作开始前，进程路径与构建特定标记都来自代理回读。

一次会话即可完成验证：服务器用该配置启动，客户端返回 navigator.userAgent 与观测到的可执行文件路径，两者与文件比较。路径匹配则配置得到证明；不匹配则服务器运行自带 Chromium，该会话的每个结果都描述一个未被选择的浏览器。两个相邻主题面对同一验证问题：面向 AI 代理的无头浏览器配置覆盖代理到浏览器的交接，Playwright 入门指南覆盖 MCP 配置必须复现的直接脚本。

Sources

• microsoft/playwright-mcp
• Playwright: BrowserType.launch
• Model Context Protocol: Introduction
• BotBrowser: Playwright getting started
• BotBrowser: CLI flags reference