如何让 Ruby Ferrum 复用已有 Chromium profile 并启用扩展？

2026-11-04数据阿明

可以通过 browser_options 指定已有的 Chromium 用户数据目录。扩展能否生效，还取决于使用的 profile、Ferrum 创建的浏览上下文和浏览器启动参数。排查时可以先设置 incognito: false，使用有界面模式，并暂时忽略 Ferrum 的默认启动参数。

现有信息没有给出 Ferrum、Chromium 的版本和扩展类型，暂时无法确定具体原因。

先确认用户数据目录的层级

这两个参数指定的是不同层级：

--user-data-dir=/tmp/chromium：用户数据根目录。
--profile-directory=Default：根目录下名为 Default 的 profile。

复制后的结构应类似：

/tmp/chromium/
├── Local State
└── Default/
    ├── Preferences
    ├── Extensions/
    └── ...

如果将原来的 Default 目录直接复制为 /tmp/chromium，再指定 --profile-directory=Default，浏览器会寻找 /tmp/chromium/Default，可能因此使用新建的空 profile。

在原浏览器中打开 chrome://version，查看 Profile Path，确认使用的是 Default、Profile 1 还是其他目录。该路径的上一级就是用户数据根目录。Chromium 用户数据目录说明

复制前，先完全退出使用源目录的浏览器。运行 Ferrum 时，也不要让其他浏览器进程同时使用目标目录，因为 Chromium 不支持两个运行中的实例共享同一个用户数据目录。

让 Ferrum 使用普通浏览上下文

指定磁盘目录后，还要确认 Ferrum 中的页面属于哪个浏览上下文。Ferrum 的配置文档说明，incognito 默认为 true；复用已有 profile 时，应显式设置为 false。Ferrum 配置文档

浏览器进程读取了某个 profile，自动化页面不一定就使用该 profile 的普通上下文。新建的无痕上下文也可能让已有状态或扩展行为与手动浏览时不同。

可以用下面的最小配置检查实际 profile 路径。示例要求所用 Ferrum 版本支持这些选项，且运行环境具备图形显示能力：

require "ferrum"

browser = Ferrum::Browser.new(
  browser_path: "/usr/local/bin/chrome",
  headless: false,
  incognito: false,
  ignore_default_browser_options: true,
  browser_options: {
    "user-data-dir" => "/tmp/chromium",
    "profile-directory" => "Default"
  }
)

begin
  browser.go_to("chrome://version")
  puts browser.at_css("body").text
ensure
  browser.quit
end

检查输出中的 Profile Path 是否指向 /tmp/chromium/Default。这一步只能确认目录选择，之后还需要在目标网站上验证扩展是否生效。

排除默认启动参数的影响

ignore_default_browser_options: true 会跳过 Ferrum 的默认参数，同时保留连接浏览器所需的参数，可以用来缩小排查范围。Ferrum 参数合并实现

不同 Ferrum 版本的默认参数可能不同。当前源码中的默认参数包含 --disable-extensions，但你贴出的命令没有这一项，因此不能直接把当前源码的默认行为认定为故障原因。Ferrum 的 Chromium 默认参数

你提供的命令包含 --disable-component-extensions-with-background-pages。它针对特定组件扩展，仅凭这一项无法断定所有普通扩展都被禁用。可以先用最小参数启动；如果扩展恢复，再逐项加回确实需要的参数，观察哪一项改变了扩展行为。

Ferrum 的 extensions: 配置用于预加载 JavaScript 文件或源码，不能用于安装 Chromium 扩展包。Ferrum 配置文档

区分旧版和新版 Headless

旧版 Headless 实现不支持加载扩展，新版统一实现则支持扩展测试。Chrome 官方扩展测试说明使用 --headless=new，现代 Chrome 的普通 --headless 已使用统一实现。扩展端到端测试说明、Chrome Headless 模式说明

问题中没有给出 Chromium 版本，命令里的 --headless 对应哪种实现，还需要结合实际版本判断。

有界面模式确认正常后，如果浏览器版本支持新版 Headless，可以在上面示例的 browser_options 中显式加入：

"headless" => "new"

使用 ignore_default_browser_options: true 时，要核对最终生成的命令，确保所需的 Headless 参数确实被传入，不能只依赖默认参数。

profile 路径正确，扩展仍未生效时怎么办？

使用相同的浏览器程序和同一份复制目录，手动启动有界面模式，打开 chrome://extensions：

如果扩展没有出现，检查目录是否复制完整，以及是否选中了正确的 profile。
如果扩展出现但被停用，查看页面显示的停用原因或兼容性提示。
如果扩展已启用但在目标网站上没有效果，检查站点访问权限、扩展报错，以及该功能是否需要用户点击才能触发。

如果手动启动也失败，优先检查 profile 或扩展本身；如果手动启动正常而 Ferrum 失败，再比较实际启动参数和页面所属的浏览上下文。