FrankenPHP实时推送怎么定义消息主题-php教程-PHP中文网

mercure.publish() 的 topic 参数必须是绝对 url；需严格匹配前端订阅的完整 url（含协议、主机、路径、大小写及编码），仅支持 rfc 3986 格式，不接受相对路径或自定义标识符。

frankenphp实时推送怎么定义消息主题

mercure.Publish() 的 topic 参数必须是绝对 URL

FrankenPHP 内置 Mercure Hub 要求所有消息主题（topic）必须是符合 RFC 3986 的绝对 URL，不能是相对路径、字符串或自定义标识符。这是协议强制要求，不是 FrankenPHP 的限制——底层 Mercure 规范本身只接受 https://example.com/posts/123 这类格式。

常见错误现象：mercure.Publish() 返回 error: invalid topic 或 HTTP 400 响应体含 "invalid topic"；浏览器端 EventSource 连接直接失败且无日志。

正确写法："https://api.example.com/users/42"、"https://localhost:8000/notifications"
错误写法："users/42"、"notifications"、"urn:topic:alerts"、"topic:news"
开发阶段可用 http://，但生产环境必须用 https://（浏览器 EventSource 会拒绝非安全上下文下的 http 主题）

主题命名要和前端订阅地址严格一致

前端用 new EventSource("https://localhost:8000/.well-known/mercure?topic=https%3A%2F%2Fapi.example.com%2Fposts%2F123") 订阅，后端 mercure.Publish() 就必须传完全相同的 URL 字符串——包括协议、主机、路径、大小写、尾部斜杠（有无都算不同主题）。

容易踩的坑：PHP 中拼接 URL 时漏掉 https:// 前缀、用 $_SERVER['HTTP_HOST'] 拼出的域名没带端口（本地开发时 localhost:8000 和 localhost 不等价）、URL 编码不一致（如空格被转成 + 而非 %20）。

btpanel phpsite 宝塔面板PHP网站

宝塔面板 PHP 网站管理：站点创建、删除、启停、PHP 版本切换、域名管理、SSL证书管理、伪静态管理、数据库管理

下载

推荐做法：统一用 parse_url() + http_build_query() 构造完整订阅 URL，再提取 topic= 后的原始值作为发布参数
调试技巧：在 mercure.Publish() 前加 var_dump($topic); die;，把输出和浏览器 Network 面板里实际请求的 topic 查询参数逐字符比对

支持通配符主题但需显式启用

Mercure 允许用 * 和 ** 匹配多级路径，例如 "https://api.example.com/posts/*" 可匹配 /posts/123 和 /posts/456/comments，但该功能默认关闭，必须在 Caddyfile 的 mercure 块中添加 publish_origins 并显式列出允许通配的源。

性能影响：通配符主题会增加 Hub 的路由匹配开销，高并发推送时可能比精确主题慢 10–15%，不建议在每秒数百次推送的场景滥用。

启用示例：

mercure {
  publisher_jwt !ChangeThisMercureHubJWTSecretKey!
  subscriber_jwt !ChangeThisMercureHubJWTSecretKey!
  anonymous
  publish_origins ["https://api.example.com"]
}

发布时仍需传完整 URL：mercure.Publish("https://api.example.com/posts/123", $payload)，通配符只控制谁有权发布，不改变 topic 格式要求

不要在 topic 里塞动态数据以外的内容

topic 应该只承载资源标识，不要混入操作语义或状态标记。比如用 "https://api.example.com/orders/789" 表示订单变更，而不是 "https://api.example.com/orders/789/status_changed" 或 "https://api.example.com/orders/789?event=updated"。

原因：Mercure 的设计哲学是“一个资源一个主题”，事件类型（created/updated/deleted）应通过消息 payload 区分，而非 topic。否则会导致订阅者无法复用连接，也违背 RESTful 资源模型。

正确结构：

$payload = json_encode([
  'type' => 'updated',
  'data' => ['status' => 'shipped']
]);

错误结构：把 type 拼进 topic 字符串，导致主题爆炸式增长，Hub 内存占用不可控

主题定义看似只是字符串拼接，但 Mercure 的 URL 强约束、大小写敏感、编码一致性、通配符权限分离这几个点，任何一个疏忽都会让推送静默失败——它不会报错，只是悄悄丢弃消息。

php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！