FrankenPHP在Symfony项目中的部署问题解析与解决方案

问题背景

在将Symfony应用程序部署到Platform.sh平台时，开发者尝试使用FrankenPHP二进制文件遇到了连接问题。错误日志显示系统尝试连接到不存在的Unix套接字文件/run/app.sock，导致请求无法正常处理。

错误分析

核心错误信息表明系统配置存在问题：

connect() to unix:/run/app.sock failed (2: No such file or directory)

这表明平台配置错误地将应用程序设置为使用FastCGI协议，而FrankenPHP并不使用这种传统的PHP-FPM通信方式。这种配置不匹配导致了连接失败。

配置问题详解

原始配置存在几个关键问题：

1. 错误的通信协议：平台默认配置尝试使用FastCGI(unix套接字)与PHP进程通信，而FrankenPHP使用不同的工作机制。

2. 冗余的Caddyfile配置：在Platform.sh环境下，实际上不需要额外的Caddyfile配置，这会增加复杂性并可能导致冲突。

3. 环境变量设置不当：部分环境变量如SERVER_NAME和FRANKENPHP_CONFIG的设置方式可能不适合Platform.sh环境。

优化后的解决方案

经过实践验证，推荐以下优化配置方案：

1. 简化安装：使用脚本直接安装最新版FrankenPHP，无需手动管理二进制文件。

2. 正确配置web部分：

   • 设置passthru: true而非指定PHP文件路径
   • 禁用FastCGI相关配置
   • 明确指定TCP协议而非Unix套接字

3. 启动命令调整：使用FrankenPHP内置的PHP服务器模式，并正确设置监听端口和文档根目录。

配置示例

applications:
  app:
    hooks:
      build: |
        curl -fsS https://raw.githubusercontent.com/upsun/snippets/main/src/install-frankenphp.sh | bash
    web:
      locations:
        "/":
          root: "public"
          expires: 1h
          passthru: true
          scripts: false
          allow: false
      upstream:
        socket_family: tcp
        protocol: http
      commands:
        start: ./frankenphp php-server --listen=localhost:$PORT --root=public

特殊场景处理

对于需要部署在子目录(如/api)下的应用，配置需要相应调整：

web:
  locations:
    '/api':
      root: 'public'
      expire: -1
      passthru: true
      index:
        - index.php
      scripts: true
      allow: true

最佳实践建议

1. 环境变量处理：确保正确处理反斜杠转义，特别是在设置APP_RUNTIME等值时。

2. 文档根目录：明确指定正确的文档根目录路径，避免使用可能不存在的环境变量。

3. 日志监控：部署后密切监控日志，确保没有隐藏的配置问题。

通过以上优化配置，可以成功在Platform.sh平台上部署基于Symfony框架并使用FrankenPHP的应用程序，避免FastCGI相关的连接问题，实现高效稳定的运行环境。