1. Mercure 简介与 Symfony 集成优势
mercure 是一个开放、高效且易于使用的协议，专为构建实时、响应式 web 应用程序而设计。它基于 server-sent events (sse) 技术，允许服务器向客户端推送更新，非常适合聊天应用、通知系统、仪表盘等场景。symfony 框架通过其 mercure bundle 提供了与 mercure hub 的无缝集成，极大地简化了实时功能的开发。
2. Mercure Hub 的安装与运行
要在 Symfony 项目中使用 Mercure，首先需要安装并运行 Mercure Hub 服务器。
2.1 下载 Mercure Hub
从 Mercure 的 GitHub 发布页面（例如 https://github.com/dunglas/mercure/releases）下载适用于您操作系统的最新版本。对于 Windows 系统，通常会下载类似 mercure_X.Y.Z_Windows_amd64.zip 的文件。
2.2 解压与准备
将下载的压缩包解压到一个您方便管理的目录。解压后，您会得到一个 mercure.exe 可执行文件以及一个默认的 Caddyfile.dev 配置文件。
2.3 运行 Mercure Hub
Mercure Hub 使用 Caddy 作为其底层的 HTTP 服务器。在运行 Mercure Hub 之前，您需要设置 JWT 密钥，用于发布者和订阅者的认证。在 PowerShell 中，可以使用以下命令运行 Mercure Hub：
$env:MERCURE_PUBLISHER_JWT_KEY='!ChangeMe!'; $env:MERCURE_SUBSCRIBER_JWT_KEY='!ChangeMe!'; .\mercure.exe run -config Caddyfile.dev
注意事项：
- !ChangeMe! 是一个占位符，在生产环境中务必替换为复杂且安全的密钥。
- Caddyfile.dev 是 Mercure 提供的开发配置文件，它通常将 Mercure Hub 暴露在 https://localhost:8000/.well-known/mercure。
成功运行后，您会在终端看到类似以下输出，表明 Mercure 服务器已启动并正在监听：
2021/11/16 01:39:58.029 INFO http server is listening only on the HTTPS port but has no TLS connection policies; adding one to enable TLS {"server_name": "srv0", "https_port": 443}
...
2021/11/16 01:39:58.135 INFO http enabling automatic TLS certificate management {"domains": ["localhost"]}
...
2021/11/16 01:39:58.143 INFO serving initial configuration这些日志表明 Caddy 服务器正在处理 HTTPS 配置，并已启用自动 TLS 证书管理，服务正在正常运行。
3. Symfony Mercure Bundle 配置
在 Mercure Hub 运行的同时，您需要在 Symfony 项目中安装并配置 Mercure Bundle。
3.1 安装 Symfony Mercure Bundle
在您的 Symfony 项目根目录执行 Composer 命令：
composer require symfony/mercure
3.2 .env 文件配置
安装完成后，Symfony 会自动在您的 .env 文件中添加 Mercure 相关的配置项。您需要根据实际情况进行调整：
# See https://symfony.com/doc/current/mercure.html#configuration # The URL of the Mercure hub, used by the app to publish updates (can be a local URL) MERCURE_URL=https://127.0.0.1:8000/.well-known/mercure # The public URL of the Mercure hub, used by the browser to connect MERCURE_PUBLIC_URL=https://127.0.0.1:8000/.well-known/mercure # The secret used to sign the JWTs MERCURE_JWT_SECRET="!ChangeMe!" ###< symfony/mercure-bundle ###
关键配置项说明：
- MERCURE_URL: Symfony 应用程序用于向 Mercure Hub 发布更新的 URL。通常是一个内部或本地 URL。
- MERCURE_PUBLIC_URL: 浏览器用于连接 Mercure Hub 的公共 URL。这个 URL 必须是客户端能够访问到的。
- MERCURE_JWT_SECRET: 用于签署 JWT 的密钥。这个密钥必须与您在运行 Mercure Hub 时设置的 MERCURE_PUBLISHER_JWT_KEY 和 MERCURE_SUBSCRIBER_JWT_KEY 保持一致。
4. 解决浏览器访问“Not Found”问题
一个常见的误区是，在 Mercure Hub 运行后，尝试通过 https://localhost/.well-known/mercure 访问它。这通常会导致“Not Found”错误，因为 Mercure Hub 默认监听在特定的端口上（例如 8000），而不是标准的 HTTPS 端口 443。
当您在浏览器中看到类似以下错误时：
Not Found The requested URL was not found on this server. Apache/2.4.46 (Win64) OpenSSL/1.1.1h PHP/7.4.25 Server at localhost Port 443
这表明您的请求被默认监听 443 端口的 Apache 服务器（或其他 Web 服务器）捕获，而不是 Mercure Hub。
解决方案：
根据您在 .env 中 MERCURE_PUBLIC_URL 的配置，以及 Mercure Hub 实际监听的端口，您应该使用正确的端口号来访问 Mercure Hub。
例如，如果您的 MERCURE_PUBLIC_URL 配置为 https://127.0.0.1:8000/.well-known/mercure，那么在浏览器中访问时，也应该带上端口 8000：
https://localhost:8000/.well-known/mercure
正确访问时，您应该会看到一个空白页面，或者一个表示连接成功的消息（例如，如果 Mercure Hub 配置了默认欢迎页）。这表明您的浏览器已成功连接到 Mercure Hub。
5. 总结与最佳实践
- 端口匹配至关重要： 确保浏览器访问 Mercure Hub 的 URL 端口与 MERCURE_PUBLIC_URL 中定义的端口以及 Mercure Hub 实际监听的端口一致。
- JWT 密钥同步： Symfony .env 中的 MERCURE_JWT_SECRET 必须与启动 Mercure Hub 时设置的 MERCURE_PUBLISHER_JWT_KEY 和 MERCURE_SUBSCRIBER_JWT_KEY 完全匹配。
- 开发与生产环境： 在开发环境中，使用 Caddyfile.dev 和本地 URL 即可。在生产环境中，您可能需要配置更健壮的 Caddyfile 或其他反向代理（如 Nginx）来代理 Mercure Hub，并使用真实的域名和更安全的 JWT 密钥。
- 理解日志： 仔细阅读 Mercure Hub 启动时的日志输出，它们会提供关于服务器监听地址、TLS 状态等关键信息，有助于诊断问题。
通过遵循上述步骤和注意事项，您将能够成功在 Symfony 5 项目中配置和运行 Mercure，为您的应用程序添加强大的实时通信能力。
