我第一次把 Selenium 塞进 Docker 容器时，心里其实有点抵触：本地写得好好的脚本，为什么非要套一层容器？后来在多人协作和 CI 环境里跑挂了无数次，才明白 docker-selenium 解决的从来不是“能不能跑”，而是“在谁的环境里跑”。它把浏览器、WebDriver、远程服务全部集成进同一个镜像，你只需要拉镜像、起容器，就能拿到一个可以被测试代码稳定连接的 Selenium 运行环境。适合自动化测试工程师、后端同学、以及所有被“环境不一致”折磨过的开发者。这篇内容我会从镜像选型、最小启动、并行编排、Headless 优化到高频问题排查，把我实际踩过的坑和验证过的做法一次说清楚。
1. 为什么要把 Selenium 塞进容器
1.1 本地环境不一致的痛点
在没有容器之前，Selenium 脚本最烦的并不是写不好，而是换台机器就跑不了。
本地 Chrome 是 108，CI 机器上是 120，WebDriver 版本跟着浏览器版本走，一旦不匹配，启动浏览器时就会报session not created或者chromedriver cannot be discovered。更难受的是服务器上根本没有图形界面，很多人第一反应是装 Xvfb，再折腾一堆显示环境变量。你以为配置好了，过两天同事在 Windows 上拉代码，一套路径全废。脚本本身一点问题没有，但环境差异把问题放大了十倍。
docker-selenium 的思路是把这些环境差异直接抹掉。浏览器、驱动、远程服务都固定在一个镜像里，本地和 CI 拉同一个 tag，跑出来的就是同一个浏览器行为。对做交付或者搞测试平台的同学来说，这种一致性比“能跑通”更重要。
1.2 docker-selenium 解决的核心问题
用容器跑 Selenium，和传统本机直连 WebDriver 比，体验上的差别非常明显。我整理了几个关键点：
- 环境交付变成一条命令：以前的“Windows 怎么装浏览器、Linux 怎么装依赖”变成
docker run，谁都能执行。 - 浏览器进程不再污染宿主机：脚本跑完容器一删，没有残留 chrome 进程，也没有占用的端口。
- 天然支持并发：一个容器不够就两个容器，或者用 Hub 加 Node 的方式横向扩展。
- 方便接入 CI：流水线里不需要安装图形依赖，直接连容器暴露的 4444 端口即可。
当然，它不是没有代价。容器里调试画面比本机麻烦，资源占用也更重，但这些问题在“稳定可复现”四个字面前都是可以接受的。
2. 镜像选型与版本匹配
2.1 先分清 standalone、hub、node 三种形态
docker-selenium 不是一个单一大镜像，而是一组相互配合的镜像。很多人第一次用，直接拉一个selenium/standalone-chrome跑起来就完事了。但如果你要搭一个真正的并行测试网格，就得理解三种形态的分工。
standalone形态最简单，一个容器里包含了 Selenium Server、浏览器和 WebDriver。你的测试代码通过远程 WebDriver 协议连到容器的 4444 端口，浏览器在容器内部启动。适合单个或少数几个测试进程的场景，也是我平时调试环境配置时最爱用的。
hub和node是 Selenium Grid 的经典架构。hub 不跑浏览器，只负责路由和调度，把测试请求分发给后面注册的 node。node 才是真正跑浏览器的角色，可以跑多个，也可以异构，比如一个 node 是 Chrome，另一个是 Firefox。需要多个环境混跑时，hub + node 比 standalone 更灵活。
我用一个表格帮你快速做选择：
| 镜像形态 | 典型镜像名 | 适用场景 |
|---|---|---|
| standalone | selenium/standalone-chrome | 单机调试、少量测试用例 |
| hub | selenium/hub | 测试请求的路由和分发 |
| node | selenium/node-chrome | 真正执行浏览器测试的实例 |
2.2 版本匹配：浏览器、驱动、Client 三者关系
容器最大的价值之一，是把浏览器和浏览器驱动打包在一起，避免你手动找对应版本。
但版本问题并没有完全消失。如果你用latest标签，镜像里的 Chrome 和 ChromeDriver 是配套的，这没问题；可一旦你本地的 Selenium Client 版本太旧，可能无法识别新版 Selenium 4 服务端返回的 capability，导致连接对不上。反过来，Client 太新而服务端镜像太旧，也可能出现不兼容的能力参数。
我的做法是“镜像尽量锁版本，Client 尽量跟主版本保持一致”。比如项目里用的 Selenium 是 4.x，那我在 CI 里就固定拉一个 4 开头的selenium/standalone-chrome镜像 tag，而不是每次都用latest。这样代码、驱动、浏览器三者之间有一个相对稳定的组合，排查问题的时候也更容易定位是哪个环节出了幺蛾子。
3. 快速跑通：最小可用的容器化测试
3.1 最简单的启动命令
如果你只想验证 docker-selenium 能不能用，下面的命令就够了：
docker run -d \ -p 4444:4444 \ -p 5900:5900 \ --shm-size=2g \ --name selenium-test \ selenium/standalone-chrome:latest这里有几个参数需要明确一下：
-p 4444:4444：把 Selenium Server 的端口映射到宿主机，测试代码连localhost:4444就能到达容器。-p 5900:5900：VNC 调试端口，方便你通过 VNC 客户端查看容器里浏览器实时画面，不需要时可以不加。--shm-size=2g：必须加的。Docker 容器的/dev/shm默认只有 64MB，Chrome 在渲染页面时非常依赖共享内存，空间不够会直接崩溃。这个参数几乎是 docker-selenium 使用中最容易踩的坑。
启动之后，可以打开浏览器访问http://localhost:4444/status，看到网格状态页面就说明服务正常。实际排查时我更喜欢用docker logs selenium-test看启动日志，失败信息一般比状态页更直接。
3.2 用 Python 连一个最小 Demo
服务起来之后，用下面这段 Python 脚本就能跑通最基本的流程：
from selenium import webdriver from selenium.webdriver.chrome.options import Options options = Options() driver = webdriver.Remote( command_executor="http://localhost:4444", options=options, ) driver.get("https://example.com") print("页面标题:", driver.title) driver.quit()关键点在于这里没有本地 ChromeDriver，也没有本地 Chrome 进程。测试代码只是把请求发给容器里的 Selenium Server，由容器内的浏览器完成页面加载。所以你本机不装任何浏览器，也不装驱动，脚本一样能跑。
第一次跑通这个流程之后，你会明显感觉到：docker-selenium 把“搭建测试环境”这件事简化成了一次镜像拉取。
3.3 别忽略容器清理和命名
调试阶段我经常忘记删容器，结果一堆积占用一堆内存。后来习惯在启动时固定容器名，测试完用一条命令清理：
docker stop selenium-test docker rm selenium-test如果你只是临时验证，可以直接加--rm，容器停止后自动删除，省得清理。但注意加了--rm的容器无法在停止后查日志，所以真正排障时我会先不加，留着日志慢慢看。
4. 并行、资源与编排
4.1 用 Compose 搭一套 Hub + Node
单容器适合验证，但真要支撑几十条用例并发，我会直接上 docker-compose，把 hub 和 node 编排在一起。下面是一个最简配置：
services: selenium-hub: image: selenium/hub:latest container_name: selenium-hub ports: - "4444:4444" environment: - SE_NODE_GRID_URL=http://localhost:4444 chrome-node-1: image: selenium/node-chrome:latest container_name: chrome-node-1 shm_size: "2g" depends_on: - selenium-hub environment: - SE_EVENT_BUS_PUBLISH=selenium-hub:4442 - SE_EVENT_BUS_SUBSCRIBE=selenium-hub:4443执行docker compose up -d后，hub 会在 4444 端口等待请求，chrome-node-1 会自动注册到 hub。测试代码连接的是 hub 地址：
driver = webdriver.Remote( command_executor="http://localhost:4444", options=options, )hub 会自己找一个可用节点来执行测试。你不需要在代码里区分节点地址，也不用手动分配浏览器到哪台机器。
这种架构的好处是浏览器节点可以单独扩容。用例多了，就再加一个chrome-node-2服务，或者直接使用docker compose scale chrome-node-1=3。需要注意的是 compose 版本和镜像版本要保持匹配，不然旧版配置里的scale在新版里可能不再支持。
4.2 资源规划：Chrome 到底多能吃内存
容器化之后，资源规划比本机跑脚本更敏感。一个 Chrome 浏览器实例在加载复杂页面时，内存轻松占用 300MB 以上，如果页面里有大量高清图片、视频和前端框架，500MB 都不稀奇。多个 session 并发时，内存会快速膨胀。
我的经验是，单节点默认最多 1 到 2 个并发 session 比较稳妥，内存给 2GB 以上，shm_size不低于 1GB。如果业务系统页面特别重，就要在节点镜像环境变量里设置SE_NODE_MAX_SESSIONS，防止一个节点被并发请求塞爆。不要盲目把SE_NODE_MAX_SESSIONS调得很大，最后往往不是便宜了吞吐，而是让所有 session 一起卡死。
也可以给容器加内存限制：
deploy: resources: limits: memory: 4g加了限制之后，Chrome 内存不够会直接崩溃，所以限制值要留余量，不要卡得太死。
5. Headless 模式与稳定性优化
5.1 headless 的正确姿势
容器里跑测试，大多数人不需要看界面，只需要结果。所以 Headless 模式很重要。
现在 Chrome 的推荐参数已经不是老的--headless,而是--headless=new。旧参数在部分页面交互上会出现奇怪的兼容问题。写 Python 测试时可以这样加：
options = Options() options.add_argument("--headless=new") options.add_argument("--window-size=1920,1080")window-size要顺手设置。默认 headless 窗口很小，很多响应式页面的元素会隐藏或者位置错乱，导致点击不到、断言失败。
有人会问：Headless 模式下截图还能用吗？可以。driver.save_screenshot()依然能产出完整截图，只是要注意等待页面渲染完成，不要刚get完立刻截图，容易截到空白页。
5.2 让容器里的浏览器更抗造
容器环境比本机简陋，浏览器稳定性更值得关注。我惯用两条兜底参数：
options.add_argument("--no-sandbox") options.add_argument("--disable-dev-shm-usage")但要说明，官方镜像通常不是用 root 用户跑的，--no-sandbox不一定需要。如果你在自定义 Dockerfile 里用了 root，或者镜像行为改了，Chrome 会要求加这个参数。安全起见，生产环境优先用非 root 用户，而不是一味关掉沙箱。
--disable-dev-shm-usage是让 Chrome 绕过/dev/shm的另一种手段，但我个人更推荐直接调大容器的shm-size。它更接近问题的根源，而且不会改变 Chrome 内部的内存行为。两种方案可以同时用，但别把--disable-dev-shm-usage当成唯一解。
5.3 调试时别只盯日志
容器里跑浏览器，最怕的就是脚本失败但日志看不出原因。遇到复杂前端交互，我会把 VNC 端口映射到宿主机，用 VNC 客户端连进去看实时画面，或者录屏回放。这一步在排查弹窗遮挡、元素被阴影层盖住、动画未结束时特别管用。
日志只能告诉你“这一步失败了”，但画面会告诉你“为什么失败”。docker-selenium 的 standalone 镜像之所以保留 VNC 端口，就是给你留了这扇调试的窗户。
6. 常见问题与排查技巧实录
6.1 高频故障速查表
我在实际使用中整理了一份高频问题表，覆盖了大部分能想到的坑：
| 现象 | 可能原因 | 解决办法 |
|---|---|---|
| 代码连不上 4444 端口 | 容器没起来或端口映射错误 | 检查docker ps，确认端口映射 |
| 浏览器会话启动后立刻崩溃 | /dev/shm空间不足 | 调大--shm-size=2g |
| 报 devtools active port 文件不存在 | Chrome 启动早期就失败 | 查看容器日志，补内存和 shm |
| 页面元素定位不稳定 | 动态渲染没有等待 | 改用显式等待WebDriverWait |
| Node 不注册到 Hub | 事件总线配置错误 | 检查SE_EVENT_BUS_PUBLISH/SUBSCRIBE |
| 镜像版本和脚本能力不兼容 | 使用latest导致版本漂移 | 锁定固定版本 tag |
6.2 我的排查基本套路
遇到问题不要急着改代码，先按顺序确认环境，这样效率最高。
第一步，看容器状态：docker ps -a。如果容器已经退出，用docker logs <container>看启动日志。官方镜像启动失败一般会直接打印出缺了什么、哪里端口被占用。
第二步，确认 Selenium 服务本身可用。访问http://localhost:4444/status，看返回的 JSON 里各节点是不是 ready 状态。如果节点没就绪，后面脚本跑多少遍都是同一个错。
第三步，用最小脚本排除业务代码干扰。不要一上来就跑整个测试套件，而是先用一个打开页面、拿标题、退出的最小用例验证链路。链路通了再逐步加业务逻辑。
这套流程帮我筛掉了至少一半的“看起来像代码问题，实际上是环境问题”的故障。docker-selenium 最省心的地方就在这里：一旦容器环境稳定，大部分脚本兼容性问题的范围会大幅缩小。
6.3 日志增长和镜像体积问题
容器跑久了日志会非常占磁盘。Selenium 节点会输出浏览器日志，如果测试用例多，一晚上能累积几个 GB。不要等磁盘满了才处理，建议在 compose 里直接配置日志轮转：
logging: driver: "json-file" options: max-size: "20m" max-file: "3"镜像体积也是真实问题。selenium/standalone-chrome动辄 1GB 以上，每次拉新 tag 都很耗时。我一般不在每次 CI 构建时拉 latest，而是把验证过的镜像固定住，只在需要升级浏览器版本时再主动更新。
如果你也用 docker-selenium 跑过一段时间，大概率会遇到比这些更离奇的鬼问题。但抛开个别诡异现象，绝大多数稳定性问题最后都会指向两个源头：一个是共享内存给得太小，一个是并发资源规划得太大。容器里跑 Chrome，先查 shm-size，其次再查内存，这两步查完，一半的崩溃问题已经解决。
