Playwright 环境配置的 5 个坑，无头模式那条最容易踩
Playwright 装起来看着简单，两行命令的事。可真到不同机器上，报错五花八门。这篇把最常遇到的 5 个坑列一遍，都是我自己或者身边人踩过的。
坑一：只装了库，没装浏览器内核
这是新手第一坑。装完库，兴冲冲跑脚本，直接报找不到可执行文件。
原因很简单：pip install playwright 只装了 Python 这一层，浏览器内核是另外下载的。得补一句：
playwright install
想省点空间，只装要用的那个就行，比如 playwright install chromium。
坑二：Linux 上缺系统依赖
库里装好了，内核也下了，一跑还是起不来——多半是系统库不齐。浏览器内核依赖一堆图形、字体、编解码相关的系统库，精简版镜像里往往没有。
这时候别再一个个手动装了：
playwright install-deps
它会把缺的系统依赖一口气补齐。在 CI 和容器里尤其管用。
坑三：无头模式跑不通，有头就正常
这条最坑，也最常见。
明明加了 headless=False 就能跑，一改成无头就失败，或者元素明明在、却一直报不可见、不可点。
原因通常是：无头模式下没有真实窗口，某些依赖布局尺寸的行为会不一样。元素高度算出来是 0、懒加载没触发、某些动画状态判断异常，都可能发生。
几个应对办法：
# 1. 显式给一个正常的视口尺寸，别用默认的
page = browser.new_page(viewport={"width": 1440, "height": 900})
# 2. 需要滚动才加载的内容，先滚一下
page.mouse.wheel(0, 1000)
还有一个信号常被忽略——无头模式下页面语言、时区、部分接口行为和真实环境有差异，结果就是"有头好好的，无头就挂"。
坑四：把无头当一个开关，忘了它变了什么
承接上一条。很多人以为 headless 只是"显不显示界面"，其实它悄悄改变了几件事。
最典型的是视口。有头模式窗口多大，视口就多大；无头模式默认给一个固定值。页面里响应式布局一判断，加载出来的可能就是另一套结构，你原来的定位自然失效。
其次是 User-Agent 和一些特性开关，两者并不完全一致。
所以切换模式之后，别默认"应该一样"，先把视口和场景对齐再排查。
坑五：容器里权限不足，进程起不来
放进容器里跑，报的错经常跟权限有关。常见的是沙箱启动失败。
browser = p.chromium.launch(args=["–no-sandbox"])
另外容器里最好显式指定用户目录和临时目录，否则某些路径没有写权限，也会在启动阶段失败。
顺手记一个排查顺序
遇到"装完了却跑不起来"，按这个顺序走，基本不会跑偏：
把这四步过一遍，绝大多数环境问题都能定位到。实在找不到头绪，就把报错原文完整看一遍，很多时候答案就写在里面，只是被我们一眼扫过去了。
互动时间：你在配环境的时候，被哪个坑卡得最久？评论区说说，说不定能帮到下一个人 👇
声明：本文为原创技术分享，请遵守相关网络协议与法律法规，勿将技术用于任何违规场景。
