FrankenPHP 1.2 Worker模式下文件上传需启用专用upload Worker、强制指定UPLOAD_TMP_DIR高速临时目录、前端请求必须发往/frankenphp-worker路径，三者缺一不可。
FrankenPHP 1.2 在 Worker 模式下处理文件上传，核心不是改 PHP 代码逻辑，而是绕过传统请求生命周期的限制，把上传行为从主应用路由中剥离出来——用专用 Worker 进程承接、隔离、可控地完成解析与落盘。
必须启用专用 upload Worker
主应用（php_server）不参与上传解析。前端上传请求必须发往 /frankenphp-worker（FrankenPHP 自动挂载的 Worker 入口），不能走 /api/upload 这类主路由路径，否则会触发主进程内存缓存上传体，极易 OOM。
- 在 Caddyfile 或 FrankenPHP 配置中显式声明 worker 块：
worker {
file /path/to/app/public/upload_worker.php
num 4
env UPLOAD_TMP_DIR /var/tmp/frankenphp-upload/
}
-
num 4：建议设为 CPU 核心数的 1/2～1/3，避免抢占主应用资源 -
env UPLOAD_TMP_DIR：强制指定高速临时目录，绕过默认/tmp的 inode 和权限风险
关键配置三要素缺一不可
Worker 模式下，上传链路依赖三个显式配置，任一缺失都会导致 $_FILES 为空或静默失败：
- max_memory_upload：FrankenPHP 自定义参数，非 php.ini 标准项，默认仅约 2MB。需在启动命令或 Caddyfile 中设为略高于业务最大单文件（如 32M），超限才落盘，否则整文件驻留内存
-
upload_tmp_dir：必须在 php.ini 中显式声明（如
upload_tmp_dir = "/var/tmp/frankenphp-upload"），并确保该目录存在、属主为运行用户（如www-data）、可写 -
file_uploads = On：检查 php.ini 是否误关；同时确认
post_max_size≥upload_max_filesize，否则 POST 在进入 SAPI 前就被截断
前端必须适配 Worker 路由与分片元信息
普通表单提交不适用。Worker 模式天然适合切片上传场景：
立即学习“PHP免费学习笔记（深入）”；
- 前端上传请求 URL 必须是
/frankenphp-worker（或你自定义的 worker 入口路径） - 每个分片请求需携带标准 multipart 元信息：
filename、chunkIndex、totalChunks、fileId（用于服务端合并识别） - 不推荐用
<input type="file" multiple>一次性传多个大文件——应逐个分片控制，并发量可控、失败可重试
后端 upload_worker.php 只做轻量落地，不做重处理
Worker 脚本职责明确：接收分片 → 验证 → 落盘临时位置 → 返回成功标识。所有耗时操作（如合并、转码、入库）应交由异步任务队列（如 Redis + Worker 进程）后续处理。
- 不要在
upload_worker.php中调用move_uploaded_file()到业务目录——它只负责暂存分片到UPLOAD_TMP_DIR下的子目录（如/var/tmp/frankenphp-upload/{fileId}/chunk_001） - 分片命名和路径由前端传递的
fileId+chunkIndex决定，便于合并时按序读取 - 合并逻辑放在独立脚本（如
merge_chunks.php）中，通过 API 触发或定时扫描完成态后执行
