根本原因是运行环境差异导致的配置与权限断层，需优先排查四类问题：php.ini上传配置未生效、临时/目标目录不可写、Web服务器层限制、路径大小写及部署遗漏。
FrankenPHP 本地能上传、服务器报错，本质不是 FrankenPHP 本身的问题，而是运行环境差异导致的配置与权限断层。FrankenPHP 作为基于 Swoole 的现代 PHP 运行时，对传统 PHP 配置（尤其是上传相关）仍完全依赖 php.ini，同时其进程模型和文件系统行为在 Linux 服务器上更“严格”，容易暴露本地开发中被忽略的细节。
以下是最常见、最需优先排查的四类原因：
php.ini 上传配置未生效或不匹配
FrankenPHP 启动时会读取 `php.ini`，但常因路径错误或未重启而沿用旧配置： - file_uploads = Off：整个上传功能被禁用，`$_FILES` 为空，框架收不到任何文件 - upload_max_filesize 和 post_max_size 不匹配：比如设了 `upload_max_filesize = 10M`，但 `post_max_size = 8M`，POST 请求会在进入 PHP 前被截断，页面可能直接空白或返回 400/500 - 修改后未重启 FrankenPHP 服务（如 `systemctl restart frankenphp` 或 `frankenphp stop && frankenphp start`），或改错了 `php.ini` 文件（可用 `php --ini` 或 `frankenphp phpinfo` 确认实际加载路径）临时目录或目标目录不可写
FrankenPHP 默认使用系统 `/tmp` 作为 `upload_tmp_dir`，但在生产服务器上常受限： - `/tmp` 所在分区磁盘满（用 `df -h /tmp` 检查） - SELinux 或 systemd 的 `PrivateTmp=true` 隔离机制拦截写入（可临时 `setenforce 0` 测试，或配置 `httpd_tmp_exec` 布尔值） - 目标上传目录（如 `public/uploads/`）未创建，或属主不是 FrankenPHP 工作进程用户（默认可能是 `www-data` 或 `nobody`），且未赋权 ```bash sudo mkdir -p public/uploads sudo chown www-data:www-data public/uploads sudo chmod 755 public/uploads ```Web 服务器层额外限制（Nginx/Apache）
FrankenPHP 常与 Nginx 反向代理配合，而 Nginx 自身有独立上传限制： - client_max_body_size 未设置或过小（如默认 1M），会导致 413 Request Entity Too Large 错误 在 Nginx 配置中添加： ```nginx location @frankenphp { client_max_body_size 50M; # 其他 proxy 设置... } ``` - 如果用 Caddy 或 Apache 代理，也要检查对应指令（如 `LimitRequestBody` 或 `Caddyfile` 中的 `body_limit`）路径、大小写与部署遗漏
FrankenPHP 对 PSR-4 加载和路径更敏感，尤其在容器或 CI/CD 部署后： - Linux 文件系统大小写敏感：控制器调用 `$this->fetch('UserAvatar')`，但模板文件是 `useravatar.php` → 报“模板不存在” - `vendor/` 未安装或 `composer install --no-dev` 未执行 → 类自动加载失败 - `runtime/` 或 `storage/` 目录硬编码路径（如 `__DIR__.'/../runtime'`）在服务器上不存在，或权限未开放写入 建议在启动脚本中加入： ```php if (!is_writable('runtime')) { @mkdir('runtime', 0755, true); @chmod('runtime', 0755); } ```不复杂但容易忽略
