Symfony搭配Caddy服务器使用教程

本文深入解析了 Symfony 项目在 Caddy 服务器上运行时常见的四大核心问题及精准解决方案：针对默认不兜底导致的 404 路由失效，必须显式配置重写规则将非静态请求交由 index.php 处理；使用 FrankenPHP Worker 模式时需替换为官方 frankenphp-worker.php 入口并避免容器重复初始化；解决 Caddy 自动 HTTPS 与 Mercure Hub 的端口和证书冲突，需禁用 auto_https 并合理反向代理；以及通过统一 UID/GID 和日志卷挂载彻底规避 Docker 中的权限与日志同步难题——每处“看似随机”的错误背后都有清晰的技术归因，掌握这四个关键点，才能让 Symfony 在 Caddy 上真正稳定、高效、安全地落地。

为什么 Symfony 项目在 Caddy 下会 404 或路由失效

根本原因不是 Symfony 本身有问题，而是 Caddy 默认不转发未匹配路径到 index.php，不像 Nginx 的 try_files $uri $uri/ /index.php?$query_string 那样隐式兜底。Caddy 的 php_server 指令只处理明确匹配 PHP 文件的请求，静态资源或路由路径（如 /admin/users）会被直接拒绝。

必须显式配置重写规则，把所有非静态文件请求交由 Symfony 入口处理：

localhost {
    root * /app/public
    php_server
<pre class="brush:php;toolbar:false"><code>@symfony {
    not file
    not {path}.php
}
handle @symfony {
    rewrite * /index.php
}</code>

}

• @symfony 是一个匹配器：排除真实存在的文件和以 .php 结尾的路径
• rewrite * 不是重定向，而是内部重写，$_SERVER['REQUEST_URI'] 仍保持原始值，Symfony 路由器能正常解析
• 若使用 Docker，确保 /app/public 是挂载路径，且 index.php 可执行权限正确（无需 chmod +x，但需容器内用户有读取权限）

Caddy 启用 Worker 模式时 Symfony 容器初始化异常

FrankenPHP 的 Worker 模式要求入口脚本（index.php）不退出、不重复初始化容器，而标准 Symfony index.php 在每次请求后会销毁 $kernel 实例。直接套用会导致服务类单例失效、Doctrine 连接复用失败、环境变量丢失等。

正确做法是改用 FrankenPHP 提供的 frankenphp-worker.php 入口，并配合 Caddyfile 中的 worker 指令：

{
    frankenphp {
        worker /app/public/frankenphp-worker.php max_workers 4
    }
}
<p>localhost {
root * /app/public
php_server
}
</p>

• frankenphp-worker.php 是 FrankenPHP 官方提供的 Worker 入口，已预加载 Kernel 并复用容器
• 必须将 APP_ENV 和 APP_DEBUG 等环境变量通过 Caddy 的 php_server 传递，例如：php_server { env APP_ENV prod }
• 不要在 frankenphp-worker.php 中调用 exit 或 die，否则 Worker 进程会退出

Caddy 自动 HTTPS 与 Symfony Mercure 配置冲突

Mercure Hub 默认监听 https://localhost:8000/.well-known/mercure，但 Caddy 的自动 HTTPS 会尝试为 localhost 申请证书（失败），并可能拦截对 :8000 的请求，导致前端订阅 Mercure 时返回 404 或 TLS 错误。

解决方案分两步：一是禁用 Caddy 对 Mercure 端口的接管，二是显式暴露 Mercure Hub 地址：

• 在 Caddyfile 中添加 auto_https off 全局指令，避免 Caddy 尝试管理 localhost 的证书
• 启动 Mercure Hub 时指定明确监听地址：MERCURE_URL=https://127.0.0.1:8000/.well-known/mercure，并在 Symfony 的 .env 中同步设置 MERCURE_URL 和 MERCURE_PUBLIC_URL
• 若需从外部访问 Mercure（如开发机浏览器），Caddy 可反向代理 Mercure：reverse_proxy https://127.0.0.1:8000，但必须在 tls 块中关闭证书验证：transport http { tls_insecure_skip_verify }

Docker 中 Caddy 与 Symfony 日志不同步或权限报错

常见现象是 Caddy 容器启动后报 open /var/log/caddy/access.log: permission denied，或 Symfony 的 var/log/prod.log 写入失败。本质是 UID/GID 不一致：Caddy 官方镜像默认以用户 nonroot:1001 运行，而 Symfony 应用目录常属 root 或其他 UID。

最稳妥的修复方式是统一 UID，并挂载日志目录为可写卷：

docker run -d \
  --name caddy \
  -p 80:80 -p 443:443 \
  -v $(pwd)/caddy_data:/data \
  -v $(pwd)/caddy_config:/config \
  -v $(pwd)/symfony_app:/app:ro \
  -v $(pwd)/logs:/app/var/log \
  -u 1001:1001 \
  dunglas/frankenphp

• -u 1001:1001 强制容器以 Caddy 镜像默认 UID 运行，避免写入 /app/var/log 权限拒绝
• /app:ro 标记应用代码为只读，符合安全最佳实践；日志单独挂载 /logs 卷，便于宿主机收集
• 不要依赖 chown -R 1001:1001 var/，因为 Docker 卷挂载后 chown 无效

Caddy 和 Symfony 搭配的关键不在“能不能跑”，而在重写规则、Worker 入口、HTTPS 管理边界和 UID 对齐这四点。漏掉任意一个，都可能表现为看似随机的 404、500 或连接超时——它们其实都有明确归因，只是错误信息藏得深。

好了，本文到此结束，带大家了解了《Symfony搭配Caddy服务器使用教程》，希望本文对你有所帮助！关注golang学习网公众号，给大家分享更多文章知识！