PHP 调用 Nginx mod_zip 模块动态打包 ZIP 文件

为什么选择 Nginx mod_zip

PHP 自带的 zip 模块通常要求源文件位于本地文件系统。如果要打包的网络地址文件较多，或者单个文件体积巨大，必须先下载到服务器临时目录再打包，这不仅消耗大量磁盘 I/O，还会长时间占用 PHP-FPM 进程，导致服务器并发处理能力急剧下降。

Nginx 提供了 mod_zip（需自行编译安装）模块。其核心原理类似 X-Accel-Redirect：PHP 负责逻辑处理，告诉 Nginx “需要哪些文件以及对应的元数据”，然后由 Nginx 在底层将这些文件实时合并压缩并流式发送给客户端。这种架构将繁重的 IO 和压缩工作交给了 Nginx，PHP 仅作为路由控制器。

配置与交互协议

要启用此功能，首先需要确保 Nginx 已加载 zip 模块。在 PHP 脚本中，你不需要生成任何二进制 zip 数据，而是需要向 Nginx 发送特定的响应头和正文内容。

第1步：设置关键响应头

PHP 必须在输出的 HTTP 头部中添加以下字段，告诉 Nginx 本次响应的正文内容是用于打包的信息：

// 声明使用 zip 模块进行处理
header("X-Archive-Files: zip");

// 可选：如果涉及中文文件名，指定编码（注意兼容性见后文）
// header("X-Archive-Charset: utf8");

第2步：构建源文件列表

响应体的每一行代表一个待打包的文件。每行的格式遵循：CRC32 SIZE URL PATH。

• CRC32：文件的 CRC32 校验值（十六进制字符串）。如果设为 -，则不支持断点续传；若已知校验值，可填写具体数值。
• SIZE：文件大小的十进制整数。
• URL：文件的实际来源地址。可以是外部公网链接，也可以是本地路径（需在 Nginx 中配置为 internal 访问权限）。
• PATH：该文件在最终生成的 ZIP 压缩包内的路径名称。

在 PHP 中可以这样输出生成：

$files = [
    // 普通示例：CRC32(-), 大小, 源地址, 目标路径
    ["-", 1024, "/path/to/image.jpg", "images/photo.jpg"]
];

foreach ($files as $file) {
    // printf 逐行输出，模拟文本流
    printf("%s %d %s %s\n", $file[0], $file[1], $file[2], $file[3]);
}

高级场景处理

创建空目录

标准的 ZIP 格式并不支持纯粹的“空文件夹”。大多数解压器通过识别以 / 结尾且大小为 0 的条目来模拟空目录。由于 mod_zip 需要从真实文件中读取数据，你需要在服务器上预先创建一个 0 字节的占位文件（例如 /var/nginx/empty_dir_marker），并在 Nginx 中将其配置为内部访问路径。

生成空目录的逻辑代码如下：

// 假设 _0 是 nginx 中的 internal 路径映射到的 0 字节文件
printf("%s %d %s %s\n", '00000000', 0, '/_0', 'new_folder/');

中文路径编码问题

ZIP 规范对中文支持较为混乱。虽然可以通过添加 X-Archive-Charset: utf8 响应头告知 Nginx 源路径采用 UTF-8 编码，但不同操作系统和解压软件的表现不一致：

• Windows 自带解压/WinRAR：WinRAR 表现较好，能正确解析 UTF-8 或 GBK 编码。Windows 原生资源管理器可能对非系统默认编码显示乱码。
• 7-Zip：有时会错误地将包含特殊字符的空目录项解析为普通 0 大小文件，而非文件夹。

建议在实际生产环境中，根据主要用户的操作系统环境调整路径编码策略，或在打包前对文件名进行标准化处理。

完成判断

配置完成后，访问该 PHP 脚本。浏览器应直接下载一个合法的 ZIP 文件。打开该文件，检查其中的文件是否齐全，路径是否符合预期，且无需在服务器硬盘上生成中间 ZIP 文件。