PHP集成Base64动态图片到PKpass失败，寻求解决方法

一、先明确PKpass图片的硬性规范 #

• 尺寸必须符合要求：比如logo为160×50px，icon为29×29px，strip为640×100px（不同凭证类型有差异，以Apple官方规范为准）
• 格式仅限PNG/JPEG，禁止带Alpha通道（透明图大概率会导致不显示）
• 图片必须放在pass包的images目录下，且在pass.json中精准引用文件名

二、Base64转存图片的PHP正确写法 #

先剥离Base64前缀，再解码写入指定目录，确保文件权限可读：

// 假设$base64Str是你的Base64图片字符串
$base64Data = preg_replace('/^data:image\/png;base64,/', '', $base64Str);
// 图片要放在pass包的images目录下，文件名要和pass.json中一致
$imageSavePath = 'your-pass-dir/images/logo.png';
// 解码并写入文件
file_put_contents($imageSavePath, base64_decode($base64Data));
// 设置可读权限
chmod($imageSavePath, 0644);

三、校验pass.json的图片配置 #

确保images字段里的文件名和实际文件完全一致（iOS区分大小写）：

{
  "formatVersion": 1,
  "passTypeIdentifier": "pass.com.your-domain.xxx",
  "serialNumber": "SN123456",
  "teamIdentifier": "YOUR_TEAM_ID",
  "images": {
    "logo": "logo.png",
    "icon": "icon.png"
  },
  // 其他凭证字段...
}

四、打包pass包的关键注意事项 #

• 必须将pass.json、images目录、manifest.json、signature文件一起压缩为ZIP，再改后缀为.pkpass
• 生成manifest.json时，要正确计算所有文件（包括图片）的SHA1哈希，iOS会校验哈希，不匹配则拒绝加载：

$passDir = 'your-pass-dir';
$manifest = [];
$files = new RecursiveIteratorIterator(new RecursiveDirectoryIterator($passDir));
foreach ($files as $file) {
    if (!$file->isFile()) continue;
    $relativePath = str_replace($passDir . '/', '', $file->getPathname());
    // 排除签名文件和系统隐藏文件
    if ($relativePath === 'signature' || $relativePath === '.DS_Store') continue;
    $manifest[$relativePath] = sha1_file($file->getPathname());
}
file_put_contents($passDir . '/manifest.json', json_encode($manifest));

五、常见排查点 #

• 打开pass包的images目录，确认图片能正常打开（排除写入失败问题）
• 用Apple本地的PassKit Validation Tool验证pass包，工具会输出具体错误
• 把带透明通道的PNG转成不透明格式（用PS或在线工具去除Alpha通道）

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