yii框架不内置ftp客户端，需用php原生ftp_*函数或封装组件；必须启用ftp扩展，递归创建目录，上传前校验文件状态，强制启用被动模式并过滤文件名。
ftp_connect + ftp_login + ftp_put 组合，或封装成组件复用。直接在 controller 里硬写 FTP 逻辑容易出错、难维护、无法复用。
PHP 的 ftp_* 函数必须启用扩展
运行 php -m | grep ftp 看是否已加载 ftp 扩展。没启用会报 Call to undefined function ftp_connect()。Windows 下检查 php.ini 是否取消了 ;extension=php_ftp.dll 的注释；Linux 下通常是 extension=ftp.so，需确认模块已编译且路径正确。Docker 环境常漏装，得在 Dockerfile 加 docker-php-ext-install ftp。
ftp_is_dir() 和 ftp_mkdir() 配合创建多级目录
FTP 协议不支持一次性创建嵌套路径（如 /test/2026/04/15），必须逐层判断并创建。别信 @ftp_mkdir($conn, '/test/2026/04/15') 能直接成功——它大概率静默失败。
- 先用
ftp_chdir($conn, $dir)尝试切换，能切进去说明目录存在 - 切换失败再调
ftp_mkdir($conn, $dir)，但只对最后一级有效 - 推荐用递归函数：先
dirname($dir)，确保父目录存在，再建当前级 - 注意权限：有些 FTP 服务器禁止在根目录下直接
mkdir，需先ftp_chdir($conn, '/')再操作
上传前必须校验 $_FILES 临时文件状态
Yii 中虽常用 UploadedFile::getInstance()，但 FTP 上传仍要回到底层 $_FILES —— 因为 ftp_put() 只接受本地文件路径，而 UploadedFile->tempName 才是那个真实路径。
- 务必检查
is_uploaded_file($_FILES['xxx']['tmp_name'])，否则可能把恶意路径传给ftp_put -
$_FILES['xxx']['error'] !== UPLOAD_ERR_OK时直接拒绝，比如超限返回UPLOAD_ERR_INI_SIZE - 不要直接拼接
$_FILES['xxx']['name']当远程路径名，需过滤掉../、空字节、控制字符等 - 二进制模式上传（
FTP_BINARY）是默认且安全的选择；FTP_ASCII仅用于纯文本，且不同系统换行符处理不可控
Yii2 中封装 FTP 组件比每次手写更可靠
把连接、登录、目录创建、上传、错误处理打包成一个 FtpClient 类，controller 里只调 $this->ftp->upload($localPath, $remotePath)。这样能统一处理重试、超时、被动模式（ftp_pasv($conn, true)）、连接复用等细节。
- 连接不能复用跨请求：每个 request 必须
ftp_connect→ftp_login→ 操作 →ftp_close - 别在
__destruct里关连接，PHP 请求结束自动释放资源，但显式关更清晰 - 错误日志必须记录完整上下文：
$conn_id、$remote_path、ftp_pwd($conn)当前路径、ftp_systype($conn)返回的系统类型 - 被动模式不是可选项：现代防火墙/NAT 环境下，主动模式（PORT）基本不通，
ftp_pasv($conn, true)必须在ftp_login后立即调用
ftp_put 超时或“Permission denied”。别依赖 ftp_nlist() 列目录来判断子目录是否存在，它在网络不稳定时可能返回空数组而非 false，要用 ftp_chdir + 异常抑制来判存。
