在 php 中强制下载文件并设置文件名，核心在于正确配置 http 响应头。你需要调用 header() 函数依次发送 content-type、content-disposition 和 content-length，随后读取文件内容并通过 readfile() 输出，最后用 exit() 终止脚本以防止多余输出干扰下载流。
Content-Disposition 头部的标准写法是什么
该头部决定了浏览器是直接在页面预览还是触发下载对话框，同时指定了文件名。标准的写法是使用 attachment 指令，并在文件名参数中使用 filename*=UTF-8''... 格式以支持非 ASCII 字符（如中文）。如果只使用 filename=...，某些浏览器可能会忽略或错误解析包含特殊字符的文件名。
<?php // 假设我们要下载一个名为 '报告.pdf' 的文件
$filePath = '/path/to/报告.pdf';
if (file_exists($filePath)) {
// 1. 设置 MIME 类型
header('Content-Type: application/pdf');
// 2. 设置 Content-Disposition
// 使用 filename* 支持 UTF-8 文件名
$fileName = '报告.pdf';
header('Content-Disposition: attachment; filename="' . basename($fileName) . '"; filename*=UTF-8''' . rawurlencode($fileName) . ''');
// 3. 设置文件大小
header('Content-Length: ' . filesize($filePath));
// 4. 清除缓冲区并输出文件
ob_clean();
flush();
readfile($filePath);
exit;
} else {
http_response_code(404);
echo 'File not found';
}
上述代码首先检查文件是否存在。接着设置 Content-Type 为 application/pdf（可根据实际文件类型调整）。关键的 Content-Disposition 行中，我们同时提供了 filename 和 filename*。filename 提供兼容性回退，而 filename*=UTF-8''... 明确告知浏览器文件名编码为 UTF-8，并使用 rawurlencode() 对文件名进行 URL 编码，确保中文或特殊字符能正确显示。最后，ob_clean() 和 flush() 用于清空服务器端可能存在的缓冲输出，readfile() 将文件内容直接写入输出缓冲区，exit 确保后续 HTML 不会被发送。
如何处理文件名中的特殊字符和冲突
当文件名包含空格、逗号或中文时，直接拼接在 header() 中可能导致解析错误。最佳实践是将文件名包裹在双引号中，并对非 ASCII 部分使用 filename*=UTF-8'' 语法配合 rawurlencode()。此外，需避免文件名中包含换行符或分号，这些字符会破坏 HTTP 头的结构。
<?php function downloadFileWithSafeName($filePath, $customFileName = null) {
if (!file_exists($filePath)) {
http_response_code(404);
return;
}
// 确定最终文件名
$finalName = $customFileName ?: basename($filePath);
// 清理文件名：移除潜在的危险字符
$cleanName = preg_replace('/[\/:*?"|]/', '_', $finalName);
// 设置 MIME 类型
$mimeType = mime_content_type($filePath);
header('Content-Type: ' . $mimeType);
// 构建安全的 Content-Disposition
// 1. 基础 filename 属性，用于旧浏览器
$quotedName = '"' . str_replace('"', '"', $cleanName) . '"';
// 2. filename* 属性，用于现代浏览器支持 UTF-8
$encodedName = rawurlencode($cleanName);
$utf8Name = "UTF-8''" . $encodedName;
header('Content-Disposition: attachment; filename=' . $quotedName . '; ' . $utf8Name);
header('Content-Length: ' . filesize($filePath));
ob_clean();
flush();
readfile($filePath);
exit;
}
// 示例调用
// downloadFileWithSafeName('/data/my file (1).txt', '我的文件.txt');
这个封装函数 downloadFileWithSafeName 增强了健壮性。它接受文件路径和可选的自定义文件名。首先通过 preg_replace 移除了 Windows 文件系统不允许的字符（如 :, *, ? 等），防止操作系统层面的错误。然后，它将文件名中的双引号转义，用于基础的 filename 属性。对于 filename*，它使用 rawurlencode() 对清理后的文件名进行编码，并加上 UTF-8'' 前缀。这样，无论文件名是纯英文、含中文还是含特殊符号，都能被大多数现代浏览器正确识别和保存。调用时只需传入路径和期望的用户可见文件名即可。
为什么下载后文件名有时显示为乱码或默认名
这通常是因为 Content-Disposition 头部未正确指定字符编码，或者浏览器无法解析提供的文件名格式。如果完全省略 filename 参数，浏览器会使用 URL 的最后一段作为默认名。如果仅使用 filename="中文.pdf" 而不使用 filename*，部分浏览器（尤其是旧版 IE 或某些移动端浏览器）可能无法正确解码 UTF-8 字符，导致乱码或截断。确保同时提供 filename 和 filename* 是解决此问题的关键。
php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
