Delphi客户端文件上传与PHP服务端接收完整方案

简介：一套基于客户端与服务端配合实现的文件上传示例，面向需要在桌面应用中开发上传功能的程序员，以及负责编写后端接收逻辑的PHP工程师。资源完整展示了联调思路：桌面端通过HTTP POST请求发送文件数据，服务端通过$_FILES接收并保存。包体共35个文件，以.dpr、.pas、.dfm、.dproj等工程源文件为主，同时包含.exe可执行文件、.dcu编译中间文件及服务端upload.php脚本，并留有若干历史备份便于对比开发过程。压缩包整体仅491KB，结构清晰，适合快速浏览。目前已有476人学习该资源，适合正在学习客户端与Web服务端联调、或想搭建简单上传场景的入门者。借助源码可以弄清如何构造上传请求、读取并传输文件，服务端如何校验文件信息并处理异常，同时兼顾基础的安全细节，是一份动手实践价值较高的参考示例。 项目标题是“delphi客户端文件上传代码和服务器端php接收代码”，这个场景我太熟了。做了这么多年桌面端开发，Delphi写客户端工具、PHP做后端的组合其实非常常见，尤其是在企业内部系统、医疗、工业自动化这些领域。Delphi处理业务逻辑和界面效率高，PHP部署简单成本低，两边一搭配，很多项目就这么跑起来了。最核心的桥梁就是文件上传，今天我就把这套完整方案掰开揉碎聊一遍，代码直接复制就能用。

1. 整体设计思路与方案选型

1.1 为什么是Delphi + PHP这个组合

先说说为什么这个组合会被大量使用。Delphi属于编译型桌面开发工具，生成的exe不依赖运行时环境，双击就能跑，特别适合做客户端工具、数据采集程序、设备管理软件。而PHP的优势在于服务端部署极简单，一个Apache或者Nginx加上PHP解释器就能跑，写个接口接收文件、存个日志、更新个数据库都非常快。

更重要的是，这组合几乎没有额外的中间件成本。不需要像Java那样装Tomcat、配置一堆环境变量，也不需要像.NET那样绑定Windows平台。内网环境里一台普通Linux服务器就能搞定，维护成本低到可以忽略不计。我在实际项目中经常遇到这种情况：工厂车间的质检程序用Delphi写，生成报告后上传到PHP搭建的内部服务器存档，这一套方案从开发到上线往往一个星期就能完成。

1.2 文件上传方案选型：为什么用multipart/form-data

Delphi客户端要往PHP服务端传文件，可选的方案其实不少。早期有人用Socket直接传裸数据流，有人用FTP，还有人用WebService。但我强烈推荐用HTTP协议的multipart/form-data方式，这是浏览器表单上传文件的同一套标准，也是PHP支持最完善的上传方式。

用这个方案的理由简单直接：

• PHP的$_FILES超全局变量天然支持multipart解析，不需要写任何额外的解析代码
• 兼容性好，Delphi自带Indy组件库的TIdHTTP和TIdMultiPartFormDataStream直接支持这种格式
• 可以同时传输文件和普通表单字段，比如上传图片的同时附带文件描述信息
• 通过HTTP协议走80端口，能穿透绝大多数防火墙限制

1.3 整体架构与数据流

整个方案的数据流是这样的：Delphi客户端读取本地文件，将文件数据封装成multipart/form-data格式的HTTP请求，通过TIdHTTP组件发送到PHP服务端。PHP服务端通过$_FILES接收文件数据，通过$_POST接收附加的表单字段，然后调用move_uploaded_file函数将临时文件移动到指定目录。

这里有个核心要点必须提前讲清楚：Delphi端的字段名必须和PHP端的接收索引严格对应。比如你在Delphi里用AddFile('userfile', 文件路径)，服务端就得用$_FILES['userfile']来取。两端字段名不一致，文件就传不上去，而且不会报错，就是静默失败，非常坑。我当年第一次联调时就被这个问题卡了半天，所以今天把它写在最前面。

2. 端到端联调方案拆解

2.1 multipart/form-data协议原理

先花点时间讲一下multipart/form-data的底层原理，因为理解了协议才能排错。这种格式的HTTP请求体是分段的，每段用boundary字符串分隔。这个boundary是客户端自己生成的随机串，例如----WebKitFormBoundary7MA4YWxkTrZu0gW，服务端根据这个boundary来切分不同的数据段。

每个文件段大致长这样：

------WebKitFormBoundary7MA4YWxkTrZu0gW Content-Disposition: form-data; name="userfile"; filename="report.pdf" Content-Type: application/pdf [文件的二进制数据] ------WebKitFormBoundary7MA4YWxkTrZu0gW--

看到没，每个文件段包含三部分：Content-Disposition声明字段名和文件名，Content-Type声明文件类型，然后是裸的文件二进制数据。文本字段的段更简单，直接跟在Content-Disposition后面换行就是字段值。

理解了这一点，你就知道为什么TIdMultiPartFormDataStream里AddFile和AddFormField要区分开了。前者生成带文件名的分段，后者生成普通的分段。PHP端解析时也是按这个规则来的，$_FILES取带文件名的段，$_POST取普通字段段。

2.2 Delphi关键组件与数据结构

Delphi端要用的核心组件是Indy全套ID，重点就两个类：

TIdMultiPartFormDataStream是专门构造multipart/form-data请求体的类，内部自动生成boundary，自动添加各段数据的头信息。它有AddFile和AddFormField两个核心方法：

TIdMultiPartFormDataStream = class(TStream) procedure AddFile(AFieldName, AFileName: string; AContentType: string = ''); procedure AddFormField(AFieldName, AValue: string); end;

TIdHTTP是HTTP客户端组件，负责把构造好的请求体发出去。核心是Post方法重载：

function Post(AURL: string; ASource: TStream; AResponseContent: TStrings = nil): string; overload;

两个组件配合使用，顺序一般是：创建流 -> 添加字段和文件 -> 执行Post -> 释放流。

2.3 Delphi端代码框架

在实际项目中，Delphi端的上传函数通常是这样的结构，我已经在多个项目里验证过这套代码，稳定可靠：

uses IdHTTP, IdMultipartFormData, IdGlobal; function UploadFile(AFilePath, AUrl: string; AFileType: string): string; var IdHTTP: TIdHTTP; FormStream: TIdMultiPartFormDataStream; ResponseStr: string; begin IdHTTP := TIdHTTP.Create(nil); FormStream := TIdMultiPartFormDataStream.Create; try IdHTTP.Request.UserAgent := 'DelphiClient/1.0'; IdHTTP.Request.ContentType := 'multipart/form-data'; IdHTTP.Request.CharSet := 'UTF-8'; IdHTTP.ConnectTimeout := 5000; IdHTTP.ReadTimeout := 30000; FormStream.AddFile('userfile', AFilePath, AFileType); FormStream.AddFormField('description', 'upload from delphi client'); FormStream.AddFormField('client_type', 'desktop'); ResponseStr := IdHTTP.Post(AUrl, FormStream); Result := ResponseStr; finally FormStream.Free; IdHTTP.Free; end; end;

注意几个容易被忽视的点：

• IdHTTP.Request.UserAgent最好设置，有些服务器配置会拦截默认的Indy UA
• ConnectTimeout和ReadTimeout必须手动设置。Indy默认超时是0表示无限等待，生产环境里一旦服务器无响应，线程会卡死。这个坑我踩过不止一次
• AddFormField只接受字符串值，如果你要传整数、浮点数，先IntToStr或FloatToStr转一下
• finally块里两个对象的释放顺序，先流后HTTP，养成好习惯

2.4 PHP端代码框架

PHP端接收代码的核心逻辑其实很简洁。一个完整的接收接口通常包含：接收文件、判断错误码、检查类型和大小、移动文件到目标目录、返回JSON结果。下面是实际可用的代码：

<?php header('Content-Type: application/json; charset=utf-8'); // 1. 判断是否有文件上传 if (!isset($_FILES['userfile'])) { echo json_encode(['code' => 1, 'msg' => '没有收到文件']); exit; } $file = $_FILES['userfile']; // 2. 检查上传错误码 if ($file['error'] !== UPLOAD_ERR_OK) { $errMsg = '上传失败'; switch ($file['error']) { case UPLOAD_ERR_INI_SIZE: $errMsg = '文件超过php.ini的upload_max_filesize'; break; case UPLOAD_ERR_FORM_SIZE: $errMsg = '文件超过表单限制'; break; case UPLOAD_ERR_PARTIAL: $errMsg = '文件只有部分被上传'; break; case UPLOAD_ERR_NO_FILE: $errMsg = '没有选择文件'; break; case UPLOAD_ERR_NO_TMP_DIR: $errMsg = '找不到临时目录'; break; case UPLOAD_ERR_CANT_WRITE: $errMsg = '文件写入失败'; break; } echo json_encode(['code' => 2, 'msg' => $errMsg]); exit; } // 3. 检查文件大小（限制为10MB） if ($file['size'] > 10 * 1024 * 1024) { echo json_encode(['code' => 3, 'msg' => '文件超过10MB限制']); exit; } // 4. 构造存储路径，按日期分目录 $uploadDir = __DIR__ . '/uploads/' . date('Ym') . '/'; if (!file_exists($uploadDir)) { mkdir($uploadDir, 0755, true); } // 5. 生成带时间戳的文件名，避免重名覆盖 $ext = pathinfo($file['name'], PATHINFO_EXTENSION); $newFileName = date('YmdHis') . '_' . mt_rand(1000, 9999) . '.' . $ext; $destPath = $uploadDir . $newFileName; // 6. 尝试移动文件 if (!move_uploaded_file($file['tmp_name'], $destPath)) { echo json_encode(['code' => 4, 'msg' => '保存文件失败']); exit; } // 7. 返回成功信息 echo json_encode([ 'code' => 0, 'msg' => '上传成功', 'url' => 'uploads/' . date('Ym') . '/' . $newFileName, 'size' => $file['size'], 'original_name' => $file['name'] ]);

这段代码里的关键点：

• $_FILES['userfile']的索引名必须与Delphi端AddFile的第一个参数一致，这是两端联调的桥梁
• UPLOAD_ERR_OK常量值是0，error字段只有等于0才说明文件完整到达服务端
• pathinfo($file['name'], PATHINFO_EXTENSION)取扩展名时是最安全的方式，避免自己写字符串拆分出现边界问题
• move_uploaded_file第二步，生成的文件名不要直接用原始文件名，一方面防止重名，另一方面防止路径穿越攻击

3. 实操过程与核心环节实现

3.1 服务端PHP接口完整实现（含防跨域）

实际部署时，PHP接口不能只写处理逻辑，还应该考虑跨域、请求方式这些细节。特别是如果你的Delphi客户端和Web管理后台不在同一个域名下，跨域问题会经常碰到。

完善的版本应该在接口开头增加CORS支持：

<?php // 允许所有来源跨域（内网环境按需调整） header('Access-Control-Allow-Origin: *'); header('Access-Control-Allow-Methods: POST, OPTIONS'); header('Access-Control-Allow-Headers: Content-Type'); // 处理浏览器预检请求 if ($_SERVER['REQUEST_METHOD'] === 'OPTIONS') { http_response_code(204); exit; } if ($_SERVER['REQUEST_METHOD'] !== 'POST') { echo json_encode(['code' => 1, 'msg' => '仅支持POST请求']); exit; } // ... 后续文件处理逻辑

然后处理兼容性问题。如果客户端的Delphi版本是D2007或更老，字符串默认是ANSI编码，而PHP端默认是UTF-8，那文件名传过来会乱码。解决办法是在PHP端对文件名做编码转换：

if (!function_exists('mb_convert_encoding')) { // 需要开启 mbstring 扩展 } $originalName = mb_convert_encoding($file['name'], 'UTF-8', 'GBK');

不过多数情况下现在的Delphi版本都支持UTF-8了，这一步根据实际情况决定加不加。

3.2 客户端Delphi上传功能的完整界面代码

如果你要做一个完整的Delphi上传Demo，界面布局大概是这样的：一个Edit用来显示要上传的文件路径，一个OpenDialog选择文件，一个Button触发上传，一个Memo或Label显示服务端返回结果。核心组件代码：

procedure TForm1.btnSelectFileClick(Sender: TObject); begin if OpenDialog1.Execute then edtFilePath.Text := OpenDialog1.FileName; end; procedure TForm1.btnUploadClick(Sender: TObject); var IdHTTP: TIdHTTP; FormStream: TIdMultiPartFormDataStream; ResponseStr: string; begin if not FileExists(edtFilePath.Text) then begin ShowMessage('文件不存在，请重新选择'); Exit; end; IdHTTP := TIdHTTP.Create(nil); FormStream := TIdMultiPartFormDataStream.Create; try IdHTTP.Request.UserAgent := 'DelphiFileUploader/1.0'; IdHTTP.Request.CharSet := 'UTF-8'; IdHTTP.ConnectTimeout := 5000; IdHTTP.ReadTimeout := 60000; FormStream.AddFile('userfile', edtFilePath.Text, ''); FormStream.AddFormField('source', 'desktop_client'); FormStream.AddFormField('upload_time', DateTimeToStr(Now)); ResponseStr := IdHTTP.Post('http://192.168.1.100/upload.php', FormStream); memoLog.Lines.Add('[回应] ' + ResponseStr); except on E: Exception do memoLog.Lines.Add('[异常] ' + E.Message); finally FormStream.Free; IdHTTP.Free; end; end;

有几个细节值得注意。TIdMultiPartFormDataStream.AddFile的最后一个参数是ContentType，传空字符串的话Indy会根据文件扩展名自动识别，大多数情况下够用了。如果你要保证服务端一定能识别某种特定类型，可以显式传application/octet-stream，让所有文件都按二进制流处理。

关于那个AddFormField('upload_time', DateTimeToStr(Now))，在D2007及更早版本要注意，DateTimeToStr的结果带本地格式的日期分隔符，如果服务器和客户端不在同一区域设置，PHP端解析可能出问题。更稳妥的做法是：

FormStream.AddFormField('upload_time', FormatDateTime('yyyy-mm-dd hh:nn:ss', Now));

3.3 服务端PHP与客户端Delphi的联调步骤

两端代码都写好之后，联调建议按照下面的顺序来，每一步都能快速定位问题：

第一步，用浏览器或Postman测试PHP接口。先把PHP服务端独立跑通，直接用Postman的form-data方式上传一个测试文件，确认服务端接口正常。这一步能过滤掉一半的问题，避免跨语言联调时不知道错在谁。

第二步，Delphi端先传一个小文件，比如几KB的文本文件。因为小文件的网络传输时间短，如果出错，错误信息能快速返回，方便排查。

第三步，检查PHP端是否收到文件。在PHP代码里临时加一行日志：

file_put_contents('./debug.log', print_r($_FILES, true), FILE_APPEND);

这一步能看到PHP实际收到的文件元信息，包括文件名、大小、类型、错误码。这个打印输出是排查联调问题最重要的手段之一，几乎能确定80%的问题源头。

第四步，确认Delphi端HTTP状态码。在Delphi的异常处理里打印E.Message和IdHTTP.ResponseCode。如果返回405说明请求方法不对，如果返回413说明文件太大，如果返回500说明PHP代码报错，这些状态码直接指向问题所在。

4. 常见问题与排查技巧实录

4.1 上传大文件时遇到的坑

这是我在实际项目里最常踩的坑，也是同事问我最多的问题。Delphi端上传一个50MB的文件到PHP，结果PHP这边一直报错或者总是只收到一部分数据。

排查下来，大概率卡在PHP的配置文件上。PHP上传文件受三个参数限制：

这里有个新手容易踩的暗坑：post_max_size必须大于upload_max_filesize。因为一个POST请求体里不只是文件数据，还包括multipart格式的协议头和表单字段数据。我只调大upload_max_filesize，没管post_max_size，结果文件超过8MB就失败，这个问题非常隐蔽。

另一个坑是脚本执行时间。文件上传完PHP还要执行move_uploaded_file移动文件，大文件在慢速网络下传输时间加上移动时间很容易超过30秒的默认限制。修改方法是编辑php.ini：

upload_max_filesize = 100M post_max_size = 110M max_execution_time = 300

改完重启Apache或PHP-FPM服务生效。如果你用的是PHP-FPM，还要检查request_terminate_timeout这个参数，它可能单独限制请求处理时间。

4.2 服务器端PHP接收不到文件的经典原因

这个问题在网上被问炸了，我亲眼见过无数个案例。现象是Delphi端执行Post不报错，请求也发出去了，但PHP端就是$_FILES为空。

按照我排查顺序，第一时间检查字段名对应。Delphi端AddFile的第一个参数和PHP端$_FILES['xxx']的索引必须一致，这个我在开头就强调过。AddFile('userfile', 路径)对应$_FILES['userfile']，AddFile('myfile', 路径)对应$_FILES['myfile']。字段名错了一个字母，整个文件就丢了，而且大部分情况下PHP不会报任何错误，只会静默地让$_FILES为空。

第二个大概率原因是没有正确设置TIdHTTP.Request.ContentType。虽然TIdHTTP.Post会自动根据流类型设置ContentType，但如果你手动覆盖了ContentType为非multipart类型，就会出问题。稳妥的做法是设置ContentType为multipart/form-data，Indy会自动在请求头里带上正确的boundary标记。

第三个原因可能和PHP版本有关。从PHP 5.4开始，CURLOPT_SAFE_UPLOAD默认设为true，如果你用curl库自测接口，@文件路径这种老语法会失效，要改用curl_file_create或者new CURLFile。但Delphi的Indy库不涉及这个问题，它走的是原生HTTP协议栈，这里只是提醒你在用其他客户端测试时注意。

4.3 乱码问题的根因与解决

Delphi 2007及以前版本，字符串是ANSI编码，默认字符集跟系统区域相关。中文Windows系统下就是GBK编码。而PHP端默认按UTF-8处理文本。于是中文文件名上传后，服务端保存的文件名乱码或者显示异常。

解决办法有两个，根据实际环境选择：

方案一：客户端主动转码。Delphi端转成UTF-8再传，用Utf8Encode函数：

var utf8Name: UTF8String; begin utf8Name := UTF8Encode('中文文件名.txt'); FormStream.AddFormField('filename', String(utf8Name)); end;

方案二：服务端转码。如果客户端代码不便改动，就在PHP端把文件名从GBK转成UTF-8：

$fileName = mb_convert_encoding($file['name'], 'UTF-8', 'GBK');

需要提前确认PHP的mbstring扩展已开启。在php.ini里找到extension=mbstring，去掉注释然后重启服务。

4.4 大文件上传超时和TCP层问题

如果是内网环境，Delphi客户端上传200MB以上的大文件，还会遇到另一个问题：上传时间太长，PHP执行超时或者客户端ReadTimeout到期。这种情况下，Delphi端的TIdHTTP.ReadTimeout不能设太小。我实测过，100MB文件在百兆局域网中传输大约需要10-15秒，千兆网络约5秒钟，设置ReadTimeout为60秒比较稳妥。

如果客户端设置了ReadTimeout := 30000只等了30秒，而文件传输加服务端处理耗时超过30秒，客户端就会抛出一个EIdReadTimeout异常，看起来像服务端出错了，其实是客户端提前放弃了等待。

另外，PHP端如果也遇到上传200MB以上大文件超时问题，可以尝试换个思路：不走PHP，改为Nginx的client_max_body_size，或者用专门的OSS存储服务。不过这是另一个话题了。

4.5 安全加固：防止恶意文件上传

说到文件上传，就不能不提安全问题。文件上传漏洞在任何语言里都是高危漏洞，Delphi上传PHP接收这个场景也不例外。虽然我们讨论的是正常的上传功能，但安全底线必须守住，防住恶意文件上传是服务端必做的功课。

推荐做以下四层防护：

第一层，扩展名白名单。只允许特定扩展名上传，其他一律拒绝：

$allowedExts = ['jpg', 'jpeg', 'png', 'gif', 'pdf', 'doc', 'docx', 'xlsx']; $ext = strtolower(pathinfo($file['name'], PATHINFO_EXTENSION)); if (!in_array($ext, $allowedExts)) { echo json_encode(['code' => 5, 'msg' => '不允许的文件类型']); exit; }

第二层，MIME类型检查。用PHP的finfo_open读取文件真实类型，防止攻击者修改扩展名伪装：

$finfo = finfo_open(FILEINFO_MIME_TYPE); $mimeType = finfo_file($finfo, $file['tmp_name']); finfo_close($finfo); $allowedMimes = ['image/jpeg', 'image/png', 'application/pdf']; if (!in_array($mimeType, $allowedMimes)) { echo json_encode(['code' => 6, 'msg' => '文件内容与声明类型不符']); exit; }

第三层，存储目录禁止执行脚本。上传目录和PHP执行目录要分开，上传目录关闭PHP执行权限。用Nginx的话可以这样配置：

location ~* /uploads/.*\.(php|php5|phtml)$ { deny all; }

第四层，文件名重写。不要使用用户提供的原始文件名作为最终存储名，改用时间戳加随机数的方式，这个我上面的代码已经实现了。这样即使攻击者上传了一个包含路径穿越符或其他恶意字符的文件名，也不会产生影响。

把这几层防护加上去，普通的上传接口基本就安全了。当然，如果是金融、医疗等强监管行业，还要考虑更多合规与安全要求，比如文件安全扫描、访问权限校验等，这些就不在这里展开了。

5. 性能优化与扩展思路

5.1 并发上传的服务器配置调优

如果你的系统有多个Delphi客户端同时向PHP服务器上传文件，就涉及到并发处理能力的问题。Apache默认的mpm_prefork模块每个请求占用一个线程，高并发场景下内存消耗比较大。更推荐使用Nginx + PHP-FPM的组合，PHP-FPM支持进程池动态调整，内存占用更可控。

PHP-FPM的调优参数一般在php-fpm.conf或pool.d/www.conf里：

pm = dynamic pm.max_children = 50 pm.start_servers = 10 pm.min_spare_servers = 5 pm.max_spare_servers = 20

max_children并不是越大越好，要根据服务器内存和每个PHP进程的内存占用算出上限。计算公式大概是：max_children = 可用内存 / 单个PHP进程平均内存。通常每个PHP-FPM进程占用内存30-50MB，一台8GB内存的服务器，max_children设置在50-80之间比较合理。你要是不确定，可以从30开始压测，观察内存增长趋势，再逐步往上调。

5.2 磁盘存储策略：按日期分目录与云存储扩展

文件上传多了以后，一个目录里堆几万个文件会让文件系统变慢，也不方便管理。我在上面的示例代码里已经实现了按年月分目录（uploads/202504/），这个思路可以继续扩展。

按日期分目录的好处是：日志清理方便，目录数量可控，检索时能按时间范围快速定位。如果你的文件还有业务属性，比如按用户分目录可以这样：

$uploadDir = __DIR__ . '/uploads/' . $userId . '/' . date('Ym') . '/';

如果你的团队后来需要把存储迁到云服务商，代码结构要先设计好。我一般会把存储层抽象成一个接口，比如StorageInterface，然后实现LocalStorage、S3Storage、AliyunOSSStorage。这样切云存储时只改一个工厂方法，客户端代码完全不用动。这个演进思路虽然简单，但在实际项目中省了不少事。

5.3 断点续传与分块上传的设计思路

大文件上传还有一个硬骨头问题：断点续传、分块上传。如果业务上经常要传几百MB的文件，一次性传输的风险很大。简单中断后就要从头再来，体验很差。

简单的做法是用Multipart分块上传思路，但需要两端配合改造：客户端把文件切割成多个分块，每个分块单独上传，服务端按顺序接收并暂存，等所有分块到齐后再合并。

这里不做完整代码实现，只分享设计思路，以免篇幅过长。核心要点有三个：

一是分块标识。每个分块需要用唯一标识区分，可以用MD5(文件名+分块序号+分块大小)生成，保证合并时顺序正确。

二是分块大小。建议设置为2MB或4MB，太小了请求数量过多会拖慢整体速度，太大了断点续传的粒度就失去意义。2MB分块上传100MB文件得到50个分块，网络中断损失最多2MB，比较合理。

三是合并策略。服务端把分块暂存在临时目录，等所有分块上传完成后，用PHP的file_put_contents加FILE_APPEND参数依次追加合并，或者用shell_exec调用系统cat命令合并。注意合并时要加锁，防止并发合并导致数据错乱。

这套方案在真实项目中我落地过几次，效果稳定。但如果你只是内部工具，文件又不超过50MB，直接整文件上传就够了，没必要为了炫技引入复杂度。

6. 实际项目中踩过的完整案例复盘

6.1 案例一：文件名乱码导致的上传失败

这个案例来自一个工厂设备数据采集项目。Delphi客户端采集设备运行状态并生成CSV文件，然后上传到PHP服务器存档。上线第一天就接到反馈，部分设备的文件名乱码，导致PHP端无法读取扩展名，文件被判定为不允许的类型。

查了两天，最后的根因是设备本身的系统区域设置不同。车间里的Windows系统有的是中文环境，有的是英文环境。中文环境生成的CSV文件名默认用GBK编码传给服务端，而PHP端pathinfo函数是纯ASCII处理，对非ASCII字符的解析就会出现异常。

解决方法是客户端在加文件名时统一转成UTF-8的ASCII兼容形式，例如强制用时间戳命名文件，同时把原始文件名放进表单字段：

FormStream.AddFile('userfile', AFilePath, 'application/octet-stream'); FormStream.AddFormField('origin_name', ExtractFileName(AFilePath));

服务端优先用origin_name作为存档名，如果为空就用生成的随机名。这个方案既保留了原始文件信息，又规避了编码问题。

6.2 案例二：服务端返回502状态码

有一次部署到测试环境，客户端上传文件时，服务端返回502 Bad Gateway。这个错误码不是PHP返回的，而是Nginx作为反向代理时返回的。问题是PHP-FPM处理请求超时，Nginx在等不到上游响应后主动断开了连接。

解决办法是调整Nginx的proxy_read_timeout和PHP-FPM的max_execution_time，把两者都调大，让请求处理时间足够覆盖大文件的上传和处理过程：

location ~ \.php$ { proxy_read_timeout 300; fastcgi_read_timeout 300; }

这是因为Nginx作为前端，必须它自己的超时时间比后端的PHP-FPM更长才能正常代理请求。

6.3 案例三：上传Excel文件为空的问题

另一个印象深刻的问题：Delphi客户端用TIdHTTP上传Excel文件，HTTP状态码是200，但PHP端收到文件大小为0。排查后定位到是TIdMultiPartFormDataStream.AddFile方法的要求——由于Indy的实现细节，要额外指定文件流从0开始读，或者传入文件路径让Indy内部打开文件。

复盘时发现，代码里误用了AddFormField传文件路径字符串，自然只传了一个字符串，而不是文件内容。这个错误虽然低级，但很典型。建议在调用AddFile前先确认本地文件确实能被访问，并且不要混用AddFormField和AddFile处理同一份文件数据。

7. 一些关于Delphi和PHP搭配的经验分享

7.1 开发流程上的建议

这套技术组合的开发效率很高，但联调时需要特别仔细。我的建议是，两端并行开发时先约定好接口文档，哪怕只是手写的一段文字说明，把字段名、文件大小限制、返回格式都写清楚。接口文档越明确，联调Bug越少。

我常用的做法是先用Postman把PHP接口完全测通，再开始写Delphi代码。这样当Delphi出问题时，可以排除服务端的因素，直接把矛头指向客户端。

7.2 项目管理和社会工程学考虑

Delphi + PHP技术栈虽然老，但在企业内部有着大量存量代码和成熟的运维经验，员工上手快，招聘替代成本低，这些都是它在当下仍然不可忽视的实用价值。

另一个低调但实际的原因是，Delphi的编译产物是单一exe文件，部署非常方便。内网环境里安装一个客户端程序，往往不需要管理员权限，直接把exe拷到桌面就能跑。这对运维人员来说，比需要安装运行时环境的方案友好太多。

我也见过一些团队把新功能逐渐从Delphi迁移到C#或Java，但由于历史数据接口等原因，老系统还在运行。客户端上传、服务端PHP接收的这套模式，在这些过渡期依然发挥着重要作用。掌握这个技能，既能在存量系统里做维护支持，也能在从零开始的小项目中快速落地，是一项实用性极强的硬功夫。

7.3 最后再分享一个小技巧

调试文件上传问题时，任何语言的客户端上传到PHP服务端，都可以先监听服务端的临时目录：

watch -n 1 ls -l /tmp/php*

如果你发现临时文件出现了瞬间又消失了，说明文件上传成功了，问题出在后续的move_uploaded_file或目录权限上。如果临时文件压根没出现，说明请求压根没到PHP——那是HTTP层或Nginx配置的问题。这个技巧能在5秒内定位到问题的大致方向，省去了大量翻日志的时间，分享给正在排查的你。

本文还有配套的精品资源，点击获取