Laravel FTP存储JS API响应报错：UTF-8字符格式异常排查

在Laravel项目中，通过JS API调用FTP存储获取响应时，触发InvalidArgumentException错误，提示内容为Malformed UTF-8 characters, possibly incorrectly encoded。

相关配置与代码 #

文件系统配置（config/filesystems.php） #

'default' => env('FILESYSTEM_DRIVER', 'ftp')

'ftp' => [
    'driver'   => 'ftp',
    'host'     => env('FTP_HOST'),
    'username' => env('FTP_USERNAME'),
    'password' => env('FTP_PASSWORD'),
    'root'     => '/web',
],

.env配置 #

FTP_HOST=exampleftpserver.com
FTP_USERNAME=userftp
FTP_PASSWORD=password123

控制器代码 #

$explode = explode('#',$lampiran->lampiran_gambar);
foreach($explode as $row){
    if($row == null){
        $row1[] = 'null';
    }else{
        $row1[] = Storage::disk('ftp')->get('/lampiranSurat/' . $row);
    }
}
if($pegawai_pejabat->jenis_jabatan_id == 1){
    return response()->json([
        'meta' => [
            'code' => 200,
            'status' => 'success',
            'message' => 'Data Ditemukan',
        ],
        'data_verifikasi' => $verifikasi,
        'lampiran_gambar' => $row1,
        'pegawai_verif'   => $pegawai_verif,
    ]);
}

错误原因 #

Storage::disk('ftp')->get()返回的是二进制文件内容（比如图片、PDF等非文本文件），直接将二进制数据放入JSON响应会触发UTF-8编码异常——JSON要求内容必须是合法的UTF-8字符串，而二进制数据包含大量非UTF-8字符。

解决方案 #

方法1：将二进制内容转为Base64编码 #

把文件内容转换为Base64字符串后再放入JSON，这样就能安全传输：

$explode = explode('#',$lampiran->lampiran_gambar);
foreach($explode as $row){
    if($row == null){
        $row1[] = 'null';
    }else{
        $fileContent = Storage::disk('ftp')->get('/lampiranSurat/' . $row);
        $row1[] = base64_encode($fileContent);
    }
}
if($pegawai_pejabat->jenis_jabatan_id == 1){
    return response()->json([
        'meta' => [
            'code' => 200,
            'status' => 'success',
            'message' => 'Data Ditemukan',
        ],
        'data_verifikasi' => $verifikasi,
        'lampiran_gambar' => $row1,
        'pegawai_verif'   => $pegawai_verif,
    ]);
}

前端拿到Base64字符串后，可通过对应方式还原文件：

• 图片：使用<img src="data:image/[格式];base64,[Base64字符串]" />
• 其他文件：将Base64转为Blob对象后下载或预览。

方法2：返回文件HTTP访问URL（推荐） #

如果FTP服务器支持通过HTTP直接访问文件，直接返回文件URL更高效，避免Base64带来的体积膨胀：

$explode = explode('#',$lampiran->lampiran_gambar);
foreach($explode as $row){
    if($row == null){
        $row1[] = 'null';
    }else{
        // 替换为你的FTP服务器对应的HTTP访问前缀
        $row1[] = 'http://your-ftp-http-domain.com/web/lampiranSurat/' . $row;
    }
}
// 后续JSON返回逻辑不变

内容的提问来源于stack exchange，提问作者gagaltotal666