---
date: 2026-05-14
tags: [testing, playwright-mcp, caddy, dev-loop]
related: docs/standards/05-development-workflow.md
---

# Playwright MCP 在云端跑，不在 Mac 上——本地 HTML 必须走公网 URL

## 背景

老 memory（来自 MyBrain）写的是「mac-playwright MCP 通过 SSH stdio 调用 Mac 上的 MCP」，
但实际当前接入的 `mcp__plugin_playwright_playwright__*` MCP **跑在云端 / 沙箱**，不在 Mac 上。
表现：

- `mcp__plugin_playwright_playwright__browser_navigate("file:///tmp/...")` → "Access to 'file:' protocol is blocked"
- `mcp__plugin_playwright_playwright__browser_navigate("http://localhost:18765/...")` → `ERR_CONNECTION_REFUSED`
  即使在 Mac 上 `python3 -m http.server` 已经监听，端口对外可达
- `mcp__plugin_playwright_playwright__browser_navigate("https://example.com")` → ✅ 正常

结论：Playwright 浏览器进程没在 Mac 上、也没在开发机上，跟两边 localhost 都不通；
但能上公网。

## 测本地静态 HTML 的正确路径

走开发机 Caddy 反代到公网域名 `*.test.jiachentao.com`（公网解析到开发机 IP）：

1. 选一个已映射的 slot 端口（`grep -n 'slot-' ~/caddy-config/Caddyfile`），
   比如 slot-3 的 `slot-3.chentao.test.jiachentao.com` → `host.docker.internal:3700`
2. 在该 slot 起 `python3 -m http.server <port> --bind 0.0.0.0`
   （**必须 0.0.0.0**，Caddy 在 Docker 里走 `host.docker.internal`，绑 127.0.0.1 会 502）
3. 公网 URL：`https://slot-3.chentao.test.jiachentao.com/<path-from-server-root>`
4. 用 `mcp__plugin_playwright_playwright__browser_navigate` 直接打这个 URL

## 不直观的坑

- **绑 127.0.0.1 → 502**：Python `-m http.server` 默认绑 0.0.0.0，但加 `--bind 127.0.0.1`
  会让 Docker 里的 Caddy 走 `host.docker.internal` 时 connection refused。每次起 server
  都要确认是 0.0.0.0
- **端口残留**：Python `-m http.server` 用 nohup 起，杀错 pid（bash pid vs python pid）
  端口仍占用。`ss -tlnp | grep :<port>` 拿真实 pid 后 kill
- **`browser_close` 调用没意义**：MCP 自己管 page lifecycle，调用返回 "No open tabs"，
  不报错也不影响。测完不需要主动 close

## 适用范围

- 任何"改完前端静态文件、想自动化验证"的场景：showcase HTML、demo 页、prototype
- 不适用：需要 Next.js dev server 编译的 React 改动 → 还是要起 `npm run dev`
  （但 Caddy 链路相同，把 `python3 -m http.server` 换成 `npm run dev` 即可）

## 反例

不要再尝试：
- `file://` URL（被 Playwright 拒）
- `localhost:<port>` 或 `127.0.0.1:<port>`（Playwright 沙箱看不到 Mac/开发机的 loopback）
- Mac 上的 http.server 通过 SSH 反向隧道暴露（Playwright 看不到反向隧道的另一端）