Mercure 服务必须与 FrankenPHP 分离部署，不能通过 php_server 指令托管；它需作为独立容器运行，并在 Caddyfile 中用 reverse_proxy 显式代理 /.well-known/mercure 路径至 mercure:3000，同时确保 JWT 密钥一致及 publishers 配置正确。
Mercure 服务必须和 FrankenPHP 分开启动，不能靠 php_server 指令托管
FrankenPHP 的 Caddyfile 中的 php_server 只处理 PHP 脚本请求，而 Mercure 是一个独立的、基于 HTTP/2 Server-Sent Events（SSE）和 WebSockets 的发布-订阅服务，它需要自己的监听端口和配置。Docker 内部网络中，Mercure 必须作为单独容器运行，否则无法被 FrankenPHP 正确代理或被客户端连接。
常见错误是试图在同一个 FrankenPHP 容器里用 mercure 指令启动 Mercure —— 这个指令只在 Caddy 的官方 Mercure 模块中存在，而 FrankenPHP 当前（v1.2+）并未内置该模块；它仅支持通过反向代理方式接入外部 Mercure 实例。
Docker Compose 中必须显式定义 mercure 服务并暴露正确端口
使用官方 Mercure Hub 镜像（dunglas/mercure）是最稳妥的方式。关键点在于：
-
ports必须暴露80和443（供 Caddy 自动 HTTPS），同时暴露3000（内部 HTTP 端口，供 FrankenPHP 反向代理用） -
environment中至少要设置MERCURE_PUBLISHER_JWT_KEY和MERCURE_SUBSCRIBER_JWT_KEY，否则启动失败 -
command要显式指定--addr :3000，避免默认绑定127.0.0.1:3000导致 FrankenPHP 容器无法访问 - FrankenPHP 容器与 Mercure 容器必须在同一 Docker 网络（如默认
bridge或自定义networks）
示例片段（compose.yaml）：
立即学习“PHP免费学习笔记（深入）”；
services:
mercure:
image: dunglas/mercure
restart: always
ports:
- "80:80"
- "443:443"
- "3000:3000"
environment:
MERCURE_PUBLISHER_JWT_KEY: '!ChangeThisOnProduction!'
MERCURE_SUBSCRIBER_JWT_KEY: '!ChangeThisOnProduction!'
MERCURE_CORS_ALLOWED_ORIGINS: '*'
MERCURE_EXTRA_DIRECTIVES: |
publishers [http://localhost:3000]
command: ["--addr", ":3000", "--demo", "--allowed-origins", "*"]FrankenPHP 的 Caddyfile 必须用 reverse_proxy 显式转发 /\.well-known/mercure
FrankenPHP 不会自动识别或路由 Mercure 请求。你必须在 Caddyfile 中手动添加反向代理规则，把所有 Mercure 相关路径（主要是 /.well-known/mercure）转给 Mercure 容器。Caddy 会自动处理 JWT 验证头、CORS、SSE 流量等细节，但前提是路径匹配准确。
注意：mercure 容器名在 Docker Compose 中是 mercure，所以 reverse_proxy 地址应为 mercure:3000，不是 localhost:3000（后者在容器内指向自己）。
示例 Caddyfile 片段（放在 localhost 块内）：
mercure.example.com {
reverse_proxy mercure:3000
}
<h1>或者复用同一域名下的子路径：</h1><p>localhost {
root public/
php_server { try_files {path} index.php }</p><h1>关键：Mercure 路径必须显式代理</h1><p>@mercure {
path /.well-known/mercure*
}
reverse_proxy @mercure mercure:3000
}JWT 密钥不一致或环境变量未注入会导致 401/403 错误
前端调用 new EventSource('/.well-known/mercure?topic=...') 或后端用 curl -X POST 推送时，如果返回 401 Unauthorized 或 403 Forbidden，大概率是 JWT 密钥没对齐。Mercure 验证 Publisher 和 Subscriber 的 JWT 是严格配对的，且必须由 FrankenPHP 应用生成的 token 使用相同密钥签名。
检查点：
- Laravel 应用中配置的
MERCURE_PUBLISH_URL和MERCURE_JWT_KEY是否与mercure容器的MERCURE_PUBLISHER_JWT_KEY完全一致（包括空格、换行） - FrankenPHP 容器是否能读取到这些环境变量（例如通过
environment:或.env文件挂载） - Mercure 容器日志中是否有
invalid JWT或signature verification failed提示
调试建议：先用 curl 手动测试 Mercure 是否可达：
curl -v http://localhost:3000/.well-known/mercure
若返回 404，说明路径没代理对；若返回 401，说明 JWT 校验已启用但密钥错；若返回空响应 + 200，说明服务就绪，问题出在应用层 token 生成逻辑。
真正容易被忽略的是 Mercure 的 publishers 配置项 —— 它控制哪些来源允许推送事件，必须显式列出 FrankenPHP 容器的 IP 或主机名（如 http://php:8000），否则即使 JWT 正确也会被拒绝。这个值藏在 MERCURE_EXTRA_DIRECTIVES 里，不是环境变量，改完要重启 Mercure 容器。
