企业官网建设流程全解析

在容器里跑浏览器自动化，最烦的一步不是装浏览器，而是装扩展。镜像构建时手动点一遍“添加到 Firefox”，容器一重建就全没了；用挂载的 profile 目录做持久化，换台机器又得重新点一次。Docker + Firefox 插件自动安装这件事，本质上要解决的是“无交互环境下，让浏览器启动那一刻扩展就已经在位”。这篇东西把我这几年来回折腾的几条路子摊开讲：policies.json 策略注入、环境变量驱动的运行时装配、以及脚本注入兜底，每条路都给出可直接抄的配置、参数选择的理由，还有那些文档里不会写、只有自己踩过才知道的坑。刚接触容器化浏览器测试的朋友可以从头看，已经在用 Selenium 或 Playwright 跑批的同行可以直接跳到策略注入和排查表那两节，你应该会有点收获。

1. 需求拆解：容器里自动装扩展到底难在哪

1.1 三个真实场景，决定了方案上限

先说清楚适用面，不然选型容易走偏。第一类是自动化测试的基线环境：跑 UI 用例时需要浏览器带着固定的扩展组合启动，比如某种辅助工具条、某种截图插件，而且每次 CI 跑出来的环境必须完全一致，不能因为镜像重建导致少一个扩展、多一个扩展。第二类是无人值守的信息采集或页面渲染服务：容器作为常驻服务跑，扩展的作用是改变页面渲染结果或者增加采集能力，这时候要求扩展在浏览器进程一起床就位，不能等脚本跑起来再慢慢装。第三类是可复现的演示环境：给同事或客户一个镜像，docker run之后打开就能看到配好的浏览器状态，省掉一堆“你先去扩展商店搜一下”的沟通成本。

这三类的共同约束是：容器里没有图形界面交互，没有人类点击，没有任何一次“确认安装”对话框能被处理。所以任何依赖“打开扩展商店、搜索、点击安装、点确认”的方案，在容器里天然不成立。你要么提前把扩展变成镜像的一部分，要么让浏览器在启动读配置的阶段就把它认下来。

1.2 四条路线的取舍对比

我实际用过的路线一共四条，先摆个表，后面逐条拆。

之所以把 policies.json 放在第一位，原因很朴素：它是声明式的。你写一个 JSON 文件，浏览器自己负责去拉、去校验、去落盘，中间不需要你的代码参与，也就不存在时序竞争、不存在“等扩展装完再操作页面”这类同步问题。而脚本注入那一条，我用了两三年，最大的感受是——它能用，但不太可靠。签名校验、首次启动的欢迎页、扩展安装的异步完成，任意一个环节出问题，用例就随机挂。

1.3 一个容易被忽略的前提：扩展签名

不管走哪条路，先在脑子里立一根桩：正式发行版的 Firefox 只加载有签名的扩展。这条规则在桌面端对普通用户是保护，对我们做容器化就是额外的一道工序。它会直接决定你能不能用“自己打包的 xpi 塞进去”这种土办法。

签名策略和构建版本强相关：

• 正式发行版（Release）：强制签名，xpinstall.signatures.required这个首选项在发行版里是被锁死的，改 user.js 也无效。
• 延长支持版（ESR）：同样强制签名，行为与发行版一致。
• 开发者版 / 每夜构建版：可以关闭签名校验，通过首选项xpinstall.signatures.required = false生效。

所以选镜像基线的时候就该想清楚：如果你的扩展是自己内部打包、没有走签名流程的，那基线必须选开发者版或每夜构建版，否则你在策略里写什么都会失败，而且失败是静默的——浏览器不会弹窗告诉你签名不对，扩展就是不见了。这个坑我在第一次做的时候足足找了半天，日志里干干净净，最后靠about:support里的扩展列表才定位到。

2. Firefox 的扩展加载机制，先搞懂再动手

2.1 profile 目录、extensions 目录与文件命名规则

Firefox 的用户数据放在 profile 目录里，扩展相关的有三处值得记住：

• <profile>/extensions/：每个扩展一个条目。如果扩展被解压放置，目录名就是扩展 ID；如果是 xpi 文件，文件名是<扩展ID>.xpi。这个命名规则是硬性的，名字对不上就等于没装。
• <profile>/prefs.js与<profile>/user.js：前者是运行期写入的偏好，后者是启动时读取并覆盖的偏好。想要“每次启动都强制某个配置”，写 user.js；写 prefs.js 会在浏览器退出时被覆盖。
• <profile>/extensions.json：扩展注册表，浏览器自动维护，别手改，改了下次启动会被重建。

容器里最麻烦的是 profile 路径不确定。Firefox 默认会用$HOME/.mozilla/firefox/<随机串>.<配置名>，那个随机串会随容器重建变化。解决办法有两个：一是显式指定 profile 路径，构建镜像时用firefox --CreateProfile "auto /opt/ffprofile"建一个固定名字的 profile，运行时用-profile /opt/ffprofile指定；二是干脆把HOME环境变量固定下来，让随机串的父路径不变。我更倾向第一种，路径绝对可控，排查问题时一眼就能找到文件。

2.2 policies.json 的加载路径与读取时机

策略文件的加载路径跟安装方式有关，Linux 下主要有两处会被检查：

• /etc/firefox/policies/policies.json：系统级路径，多个安装版本共用。
• <安装目录>/distribution/policies.json：安装目录级路径，比如 Debian 系的firefox-esr通常在/usr/lib/firefox-esr/distribution/policies.json。

两个都存在时，安装目录级优先。我的习惯是统一放/etc/firefox/policies/policies.json，因为它跟具体安装路径解耦，换个发行版镜像也不用改 Dockerfile 里的路径。

读取时机非常关键：只在浏览器启动、初始化策略引擎的那一瞬间读一次。浏览器跑起来之后你再改这个文件，一点用都没有，必须重启浏览器进程。这一点决定了后面入口脚本的设计——所有动态生成策略的动作必须发生在firefox命令执行之前，不能是“先启动再补”。

2.3 容器环境里三个高频失败点

第一个是权限。容器里如果以非 root 用户运行（应该这么做），策略文件必须对这个用户可读；profile 目录必须可写。我见过一次镜像里 policy 文件是 root 属主、权限 600，普通用户读不到，浏览器安安静静地忽略了这个文件，什么提示都没有。

第二个是路径污染。如果你在 Dockerfile 里装了两套浏览器（比如系统包一套、官方压缩包一套），策略文件可能放到了另一套的读取路径下。用which firefox和firefox --version确认你实际执行的是哪一个，再对照它的安装目录放文件。

第三个是首次运行的初始化竞争。浏览器第一次启动会创建 profile、写入默认偏好、可能弹出首次运行页面。如果这时候你的自动化脚本立刻去操作页面，很可能拿到的是一个还没就绪的窗口。策略注入的好处是把“装扩展”这个动作提前到了这个初始化阶段之前，但页面操作的等待逻辑还是得自己写好。

3. 环境准备：镜像基线与构建上下文

3.1 镜像选型，别一上来就用最大的那个

选基线遵循一个原则：能跑起来就行，别为了省事用带桌面的完整发行版。带桌面的镜像动辄一两个 G，构建慢、传输慢、CI 拉取更慢。我一般用精简版发行版打底，装浏览器包，再把不需要的东西清掉。

Debian 系有个好处，firefox-esr这个包在官方仓库里就有，apt-get install一句话搞定，版本也相对固定，对可复现性友好。缺点是这个包的版本会跟随发行版更新节奏，不会是最新的。如果你需要特定版本的行为（比如某个策略字段只在较新版本才支持），那就得下官方压缩包自己解压，代价是要自己处理依赖库。

无头模式的依赖是个细节。--headless不需要 X 服务器，但仍然链接了一堆图形库，缺了会直接报error while loading shared libraries。精简镜像里这些库可能不在，稳妥的做法是装完浏览器后跑一次firefox --headless --version，能打印出版本号说明依赖齐了。

3.2 构建上下文的三种组织方式

第一种，扩展文件随镜像走。把 xpi 放在构建上下文里，COPY进镜像，策略里用file://指向它。优点是构建产物自包含，运行时不需要网络；缺点是每次换扩展版本都得重新构建镜像。

第二种，策略文件随镜像走，扩展运行时下载。策略里的install_url用https://地址，浏览器启动时自己去拉。优点是不用管扩展文件，升级版本改个 URL 就行；缺点是对网络有依赖，断网环境下启动会失败，而且拉取失败同样是静默的。

第三种，全部运行时注入。镜像里什么都不放，启动时由入口脚本根据环境变量生成策略文件、下载或拷贝扩展。灵活性最高，适合一个镜像服务多种业务线，但脚本逻辑要写扎实，还得处理幂等。

我的默认选择是第二种加一层本地缓存：镜像里预置常用扩展的 xpi，策略指向file://，需要临时换扩展时用环境变量覆盖成https://。这样常规场景完全离线可用，特殊场景又能灵活调整。

3.3 一个最小可用的 Dockerfile 骨架

先把地基搭好，后面所有方案都在这个骨架上改。

FROM debian:bookworm-slim ENV DEBIAN_FRONTEND=noninteractive \ HOME=/home/ff \ MOZ_HEADLESS=1 RUN apt-get update \ && apt-get install -y --no-install-recommends \ firefox-esr \ ca-certificates \ curl \ unzip \ python3 \ fonts-noto-cjk \ && rm -rf /var/lib/apt/lists/* RUN useradd -m -d /home/ff -s /bin/bash ff \ && mkdir -p /home/ff/.mozilla /opt/ff/ext /opt/ff/policies \ && chown -R ff:ff /home/ff /opt/ff COPY ext/ /opt/ff/ext/ COPY policies/ /opt/ff/policies/ COPY entrypoint.sh /usr/local/bin/entrypoint.sh RUN chmod +x /usr/local/bin/entrypoint.sh \ && chown -R ff:ff /opt/ff USER ff WORKDIR /home/ff ENTRYPOINT ["/usr/local/bin/entrypoint.sh"] CMD ["--headless", "--no-remote"]

几个点解释一下。fonts-noto-cjk是给中文页面渲染用的，不加的话截图里全是方块，这个坑很隐蔽，因为浏览器本身跑得好好的。--no-remote是必须的，不加的话当容器里还有别的浏览器进程时，新命令会被转发给已有进程导致行为诡异。HOME固定下来，profile 路径就固定在/home/ff/.mozilla/firefox，方便挂载和排查。

镜像构建完之后第一件事是验证依赖：

docker run --rm ff-base --version

能打印出版本号，说明二进制层面没问题。如果报共享库缺失，用ldd $(which firefox-esr) | grep "not found"列出来，逐个补包。

4. 方案一：policies.json 策略注入，首选路线

4.1 ExtensionSettings 的字段含义与写法

这是整个方案的核心。策略文件是个 JSON，扩展相关的配置放在ExtensionSettings下面，键是扩展 ID，值是安装规则对象。

{ "policies": { "ExtensionSettings": { "addon-a@example.org": { "installation_mode": "force_installed", "install_url": "file:///opt/ff/ext/addon-a.xpi" }, "addon-b@example.org": { "installation_mode": "normal_installed", "install_url": "https://example.net/downloads/addon-b.xpi" }, "addon-c@example.org": { "installation_mode": "blocked" } } } }

四个字段值得说清楚：

• installation_mode有五个取值：allowed（允许用户自己装）、blocked（禁止安装）、force_installed（强制安装且用户不能移除）、normal_installed（安装但用户可以移除）、allowed之外的取值都会改变扩展列表的呈现方式。测试环境我一般用force_installed，避免某些用例误点移除按钮导致后续全挂。
• install_url支持https://和file://，不支持http://。这一条很多人栽过，写了 http 地址，浏览器就是不装，日志里也没有明显报错。如果你的扩展源只有 http，那就只能下载到本地再用file://。
• 键名必须是扩展的真实 ID，不是扩展名称。ID 怎么拿？装好扩展后看about:support里的扩展列表，或者解压 xpi 看manifest.json里的browser_specific_settings.gecko.id（旧版本叫applications.gecko.id）。写错了不报错，就是不装。
• install_url指向本地文件时，路径是容器内路径，不是宿主机路径。这个听起来很蠢，但我在群里见过不止一次有人写宿主机路径。

4.2 打包进镜像还是运行时挂载

两种都行，选哪种取决于你的变更频率。

打进镜像的写法就是 Dockerfile 里COPY policies/ /etc/firefox/policies/。好处是镜像自包含、行为确定；坏处是改一行 JSON 就要重新构建。构建缓存做得好的话其实也不慢，因为COPY放在靠后的层，前面装包的层都命中缓存。

运行时挂载的写法：

docker run --rm \ -v "$(pwd)/policies.json:/etc/firefox/policies/policies.json:ro" \ ff-base --version

注意挂载单个文件时，如果宿主机文件不存在，Docker 会自动创建一个目录挂进去，然后浏览器读到一个目录、读取失败、静默忽略。这个坑很经典，第一次遇到会怀疑人生。较新版本的 Docker 支持--mount type=bind加--mount的报错更明确，建议用那个。

我的实践是策略文件打进镜像，扩展文件也打进镜像，运行时只通过环境变量做“追加”或“覆盖”，不做替换。这样最坏情况是可预测的：环境变量写错了，最多是覆盖没生效，基础扩展组合还在。

4.3 三行命令验证策略是否生效

验证方式别靠猜，Firefox 内置了一个页面专门看策略：about:policies。无头模式下看不到页面，但可以用两种方式间接验证。

第一种，看扩展文件是否落盘：

docker run --rm ff-base --headless --screenshot /dev/null about:blank >/dev/null 2>&1 docker run --rm ff-base ls -la /home/ff/.mozilla/firefox/

更直接的是启动一次浏览器让它初始化 profile，然后检查extensions目录：

docker run --rm ff-base bash -c \ 'timeout 20 firefox-esr --headless --no-remote about:blank >/dev/null 2>&1; \ find /home/ff/.mozilla -name "*.xpi" -o -name "addon-*" | head'

第二种，用--screenshot截图一个本地页面，页面上用browser.runtime之外的间接方式探测（比如扩展会修改页面特征的场景）。这个方法依赖扩展本身的行为，不通用，只适合做端到端确认。

还有一个更工程化的做法：启动后让浏览器跑一段非常短的脚本，通过 WebDriver 的about:support抓取扩展列表。这个放在下一节脚本注入里一起讲。

5. 方案二：环境变量驱动的运行时装配

5.1 为什么要这层，直接写死不香吗

写死当然香，一个镜像一个用途，职责清晰。但现实里经常是一个基础镜像要服务多条流水线，每条流水线的扩展组合还不一样。这时候如果每个组合都构建一个镜像，镜像仓库很快就堆成垃圾场，而且改一个扩展版本要重新构建所有镜像。

环境变量这层的价值在于把“扩展组合”变成运行时参数，镜像只需要一个。代价是入口脚本要写扎实，得处理变量解析、路径拼接、幂等、失败回退。这层逻辑写好了，后面加新扩展只是加个环境变量的事。

5.2 变量设计：别搞太复杂

变量设计上我踩过一个坑：一开始设计成FIREFOX_EXT_1_ID、FIREFOX_EXT_1_URL、FIREFOX_EXT_2_ID……结果扩展数量一多，环境变量列表长得没法看，还容易漏。后来改成一条变量传多个扩展，格式用ID|URL|MODE三元组，多条之间用分号隔开：

FIREFOX_EXTS="addon-a@example.org|file:///opt/ff/ext/a.xpi|force;addon-b@example.org|https://example.net/b.xpi|normal"

解析逻辑用 shell 就能写，不需要引入 Python。分隔符选|和;是因为这两个字符在扩展 ID 和 URL 里都不会出现（扩展 ID 一般是邮箱格式或 UUID，URL 里|需要转义，正常下载链接不会有）。

5.3 入口脚本：二十行解决战斗

#!/bin/bash set -euo pipefail POLICY_DIR=/etc/firefox/policies POLICY_FILE="$POLICY_DIR/policies.json" mkdir -p "$POLICY_DIR" if [ -n "${FIREFOX_EXTS:-}" ]; then # 从镜像内置的策略出发，避免覆盖掉其他非扩展类策略 if [ -f "$POLICY_DIR/policies.base.json" ]; then cp "$POLICY_DIR/policies.base.json" "$POLICY_FILE" else echo '{"policies":{"ExtensionSettings":{}}}' > "$POLICY_FILE" fi IFS=';' read -ra ENTRIES <<< "$FIREFOX_EXTS" for entry in "${ENTRIES[@]}"; do [ -z "$entry" ] && continue IFS='|' read -r ext_id ext_url ext_mode <<< "$entry" if [ -z "$ext_id" ] || [ -z "$ext_url" ]; then echo "[entrypoint] 跳过不完整条目: $entry" >&2 continue fi ext_mode="${ext_mode:-force_installed}" python3 - "$POLICY_FILE" "$ext_id" "$ext_url" "$ext_mode" <<'PY' import json, sys path, eid, url, mode = sys.argv[1:5] with open(path) as f: data = json.load(f) data.setdefault("policies", {}).setdefault("ExtensionSettings", {})[eid] = { "installation_mode": mode, "install_url": url, } with open(path, "w") as f: json.dump(data, f, ensure_ascii=False, indent=2) PY done fi exec firefox-esr "$@"

这里用 Python 改 JSON 而不是用sed或jq，原因是jq在精简镜像里不一定有，装一个又增加体积；Python 基本都在。如果你的镜像里已经有jq，换jq更轻量。

脚本里两个细节值得强调。一是set -euo pipefail，不加的话某个解析失败会被静默吞掉，容器正常启动但扩展没装上，排查成本极高。二是exec启动浏览器，让浏览器进程接管 PID 1，这样docker stop发的信号能直接送到浏览器，不会出现停不下来、十秒后被强杀的情况。

5.4 幂等与并发

入口脚本在容器里只跑一次，理论上不需要考虑并发。但如果你的启动方式是docker exec进去改配置再手动重启浏览器，就可能出现两个进程同时写策略文件。这种情况我建议加个简单的文件锁，或者干脆约定“只允许在容器启动时装配，运行期不修改”。

另外，FIREFOX_EXTS里的file://路径必须是真实存在的文件。脚本里加一次存在性检查，比让浏览器静默失败要好得多：

case "$ext_url" in file://*) local_path="${ext_url#file://}" if [ ! -f "$local_path" ]; then echo "[entrypoint] 扩展文件不存在: $local_path" >&2 [ "${FIREFOX_STRICT:-1}" = "1" ] && exit 1 fi ;; esac

FIREFOX_STRICT默认 1 是刻意的：宁可容器起不来，也不要带着半残的扩展组合跑测试，后者会让你的用例结果变得没法解释。

6. 方案三：脚本注入，兜底但不做主路

6.1 用 WebDriver 装上扩展的两种姿势

Python 生态里最常见的是 Selenium 配 geckodriver。装扩展有两条路：一是通过 profile 预置首选项，让浏览器启动时自动装；二是启动后用扩展安装接口。

先说第一条，本质上是把策略注入换成首选项注入：

from selenium import webdriver from selenium.webdriver.firefox.options import Options import os, base64 opts = Options() opts.add_argument("-headless") opts.add_argument("-profile") opts.add_argument("/home/ff/.mozilla/firefox/auto") opts.set_preference("xpinstall.signatures.required", False) driver = webdriver.Firefox(options=opts) driver.get("about:blank") print(driver.capabilities.get("moz:profile")) driver.quit()

注意xpinstall.signatures.required这一行，只有在开发者版或每夜构建版上才有效，正式发行版会被锁死忽略。这一段在排查时一定要先确认版本，否则你会以为代码写错了。

第二条路，启动后安装。Firefox 的 WebDriver 实现提供了一个扩展安装接口，可以通过驱动去调：

driver = webdriver.Firefox(options=opts) with open("/opt/ff/ext/addon-a.xpi", "rb") as f: payload = base64.b64encode(f.read()).decode() driver.install_addon(payload) # 具体参数形式以所用驱动版本为准

不同版本的驱动和客户端库对这个接口的签名不太一样，有的接受文件路径，有的接受 base64 字符串。用之前先pip show看一眼版本，对照官方文档，别照抄几年前的文章。我吃过这个亏，抄了个老写法，报了个完全看不懂的参数错误。

6.2 user.js 与 about:config 的关系

user.js是在 profile 目录下的一个纯文本文件，每行一条首选项，格式是user_pref("键", 值);。浏览器每次启动读它，并把值写入prefs.js。想要某个配置“永远压回去”，写 user.js 是唯一可靠的方式。

一个典型的 user.js 长这样：

user_pref("browser.startup.homepage", "about:blank"); user_pref("browser.startup.page", 0); user_pref("browser.shell.checkDefaultBrowser", false); user_pref("datareporting.policy.dataSubmissionEnabled", false); user_pref("toolkit.telemetry.enabled", false); user_pref("xpinstall.signatures.required", false);

前几条是容器里必配的，不然每次启动都会尝试打开主页、检查默认浏览器、上报数据，既慢又产生噪音。尤其browser.shell.checkDefaultBrowser，无头模式下这个检查虽然不弹窗，但仍然会拖慢启动。

要说清楚一件事：user.js 装的不是扩展，它只改首选项。网上有些文章把“通过 user.js 安装扩展”混为一谈，实际上是通过首选项 + profile 预置文件实现的，两回事。搞清楚这个边界，排查时才不会被误导。

6.3 首次启动时的时序陷阱

脚本注入最不稳的地方在这里。浏览器进程起来之后，扩展的安装是异步的，代码执行到driver.get()的时候，扩展可能还没注册完成。表现出来就是：用例第一次跑通，第二次挂，换个机器又通了。

处理思路有两个。一个是装完扩展后显式等待一段时间，或者轮询某个只有扩展生效后才会出现的特征。另一个是干脆放弃运行期安装，回到启动期安装，让浏览器在“页面可操作”之前就已经完成了扩展加载。后者才是我现在的主力做法，脚本注入只留在调试场景用。

如果一定要运行期装，等待逻辑可以这样写：

import time def wait_addon_ready(driver, timeout=20): end = time.time() + timeout while time.time() < end: try: # 用一个只有扩展加载后才会响应的内部页面做探针 driver.get("about:debugging") if "扩展" in driver.page_source or "Extensions" in driver.page_source: return True except Exception: pass time.sleep(0.5) return False

探针页面选哪个，取决于你的扩展行为，没有通用答案。核心思想就是：不要用sleep(5)这种硬等待，它在快机器上浪费时间，在慢机器上又不够。

7. 完整实操：五步跑通一个可复现的镜像

7.1 目录结构与文件清单

先把工程结构摆出来，照这个建目录，后面命令可以直接复制。

ff-auto/ ├── Dockerfile ├── entrypoint.sh ├── ext/ │ └── addon-a.xpi └── policies/ └── policies.base.json

policies.base.json只放非扩展类的策略，比如禁用遥测、禁用首次运行页面：

{ "policies": { "DisableTelemetry": true, "DisableFirefoxStudies": true, "OverrideFirstRunPage": "", "OverridePostUpdatePage": "", "ExtensionSettings": {} } }

OverrideFirstRunPage设成空字符串是有效的写法，它的作用是阻止首次运行页面打开。这个字段在部分版本上的行为有过变化，如果设了没用，退回到browser.startup.homepage=about:blank加browser.startup.page=0的组合。

7.2 构建与启动

docker build -t ff-auto:latest . docker run --rm ff-auto:latest \ --headless \ --screenshot /tmp/shot.png \ about:blank

第二条命令会启动一次浏览器、截一张空白页、退出。跑完之后容器里会留下 profile 目录，但因为是--rm，容器退出就没了。想看落盘结果就换成：

docker run --rm ff-auto:latest bash -c \ 'timeout 25 firefox-esr --headless --no-remote about:blank >/dev/null 2>&1 || true; \ ls -la /home/ff/.mozilla/firefox/auto/extensions/ 2>/dev/null || \ find /home/ff/.mozilla -maxdepth 4 -type d -name extensions'

能看到extensions目录下有addon-a@example.org这样的条目，说明策略生效了。如果目录存在但为空，往下看排查表。

7.3 五条验证清单

构建完一次，按这个顺序过一遍，基本不会漏：

1. firefox-esr --version能正常输出，说明二进制和依赖没问题。
2. ls /etc/firefox/policies/policies.json存在，且ff用户可读。
3. 策略文件是合法 JSON，用python3 -m json.tool policies.json校验一遍，少个逗号这种事真的发生过太多次。
4. ext/下的 xpi 在容器内路径与策略里的install_url完全一致，注意大小写。
5. 启动一次后extensions目录下有对应条目。

这五条里最容易出问题的是第四条和第三条。JSON 语法错误是完全静默的，浏览器不会告诉你“你的策略文件解析失败了”，它只会当作没有这个文件。所以我把 JSON 校验写进了构建阶段：

RUN python3 -m json.tool /opt/ff/policies/policies.base.json > /dev/null

构建时挂了总比运行时空转好。

8. 常见问题与排查速查表

8.1 扩展不生效的分层排查法

不要一上来就怀疑策略文件，按层往下找，效率高很多。

8.2 无头模式特有的三个坑

第一个，字体缺失导致渲染异常。扩展装上了、页面渲染了，但中文全是方块。这个不影响扩展功能，但会影响截图类用例的判定。精简镜像里补fonts-noto-cjk或等宽的替代品。

第二个，窗口尺寸默认很小。无头模式默认视口可能只有 800x600，某些依赖响应式布局的扩展会走到移动端分支，行为跟你的预期不一致。用--width=1920 --height=1080显式指定。

第三个，部分扩展的界面元素在无头模式下不初始化。带弹出面板、带侧边栏的扩展，其界面部分在无头环境里可能根本不创建，但后台逻辑仍然跑。所以用扩展的界面特征做探针会误判，要用后台行为做探针。

8.3 我踩过的几个坑，写下来省你时间

坑一：--no-remote忘了加。容器里如果之前有一个浏览器进程在跑（比如你docker exec进去调试留下的），新起的命令会被转发过去，行为完全不可预期。加上就干净了。

坑二：改了策略没重启。我在容器里docker exec进去改策略文件，然后跑脚本，怎么都不生效。花了二十分钟才想起来策略只在启动时读。现在的做法是改完直接重启容器，不在运行中的容器里改配置。

坑三：以为force_installed等于“扩展一定可用”。它只保证扩展到位的策略意图，如果扩展本身在目标版本上不兼容，浏览器会把它禁用掉，策略层面仍然显示已安装。这种情况要去about:support里看扩展状态，别只看文件在不在。

坑四：扩展版本和浏览器版本不匹配。有些扩展声明了strict_min_version，浏览器版本低于这个值就不会加载。容器里的浏览器版本是固定的，扩展却在自动更新，某天突然就不工作了。解决办法是扩展也锁定版本，用固定的 xpi 文件而不是install_url拉最新。

坑五：镜像层缓存导致的“幽灵扩展”。你在COPY ext/之前改了文件，但因为 Dockerfile 里层顺序的问题，缓存没失效，最终镜像里还是旧文件。确认办法是docker run --rm ff-auto ls -l /opt/ff/ext/看文件时间戳和大小。构建时给COPY加个--checksum或者调整层顺序能缓解。

8.4 一个建议的工程化收尾

如果你打算长期维护这套东西，有两个习惯值得养成。

一是把扩展清单单独抽成一个文件，比如ext-manifest.json，记录扩展 ID、版本、来源、校验值。Dockerfile 和入口脚本都从它派生，避免"策略里写了一套、脚本里又写了一套"这种不一致。

二是在 CI 里加一条冒烟测试，构建完镜像后真正启动一次浏览器，检查extensions目录的条目数量与清单一致。这条测试比任何单元测试都值钱，因为它测的是最终产物。

我自己现在的流程就是这样：清单文件是唯一真相，Dockerfile 依赖它构建，冒烟测试验证它，入口脚本只负责运行时覆盖。跑了大半年，没有再出现过“某个镜像的扩展莫名其妙少一个”这种事。最开始那一版没有清单，全靠人记，出过两次事故，都是版本升级后某个扩展悄悄失效，等到用例大面积失败才发现。列表和冒烟测试这两样东西，加一次，之后一直省心。