如何用 PHP 的 fputcsv 函数将数组数据正确写入 CSV 文件？详细步骤是什么？

M66 2025-06-26

在开发过程中，CSV 文件常用于数据导出与数据交换。PHP 提供了一个非常方便的内置函数 fputcsv()，用于将数组格式的数据写入 CSV 文件。本文将详细介绍如何使用 fputcsv() 函数将数组正确写入一个标准的 CSV 文件中。

一、什么是 fputcsv？

fputcsv() 是 PHP 提供的一个函数，它的作用是将数组格式的数据按 CSV 格式写入打开的文件资源中。该函数会自动处理必要的分隔符、引号、换行符等问题，避免手动拼接带来的错误。

函数原型如下：

fputcsv(resource $stream, array $fields, string $separator = ",", string $enclosure = "\"", string $escape = "\\"): int|false

参数说明：

$stream：文件句柄，使用 fopen() 打开的资源。
$fields：要写入的一维数组，每个元素代表 CSV 文件中的一列。
$separator：字段之间的分隔符，默认为逗号（,）。
$enclosure：字段值的包围字符，默认是双引号（"）。
$escape：转义字符，默认是反斜杠（\）。

二、准备要写入的数据

假设我们有一组用户数据，希望将其写入 CSV 文件中：

$data = [
    ['用户名', '邮箱', '注册时间'],
    ['张三', 'zhangsan@m66.net', '2025-06-10 10:00:00'],
    ['李四', 'lisi@m66.net', '2025-06-10 11:20:00'],
    ['王五', 'wangwu@m66.net', '2025-06-10 12:35:00']
];

三、写入 CSV 文件的完整代码示例

我们希望将上面的数据写入名为 users.csv 的文件中：

<?php

// 要写入的 CSV 文件路径
$filename = 'users.csv';

// 以写入模式打开文件（如果文件不存在会自动创建）
$fp = fopen($filename, 'w');

if ($fp === false) {
    die("无法打开文件: $filename");
}

// 要写入的数据
$data = [
    ['用户名', '邮箱', '注册时间'],
    ['张三', 'zhangsan@m66.net', '2025-06-10 10:00:00'],
    ['李四', 'lisi@m66.net', '2025-06-10 11:20:00'],
    ['王五', 'wangwu@m66.net', '2025-06-10 12:35:00']
];

// 循环每一行数据并写入文件
foreach ($data as $row) {
    fputcsv($fp, $row);
}

// 关闭文件句柄
fclose($fp);

echo "CSV 文件写入完成。\n";

四、输出到浏览器下载（可选）

如果你不想将文件保存到服务器，而是直接让用户下载这个 CSV 文件，可以用如下方式：

<?php

header('Content-Type: text/csv');
header('Content-Disposition: attachment; filename="users.csv"');

$fp = fopen('php://output', 'w');

$data = [
    ['用户名', '邮箱', '注册时间'],
    ['张三', 'zhangsan@m66.net', '2025-06-10 10:00:00'],
    ['李四', 'lisi@m66.net', '2025-06-10 11:20:00'],
    ['王五', 'wangwu@m66.net', '2025-06-10 12:35:00']
];

foreach ($data as $row) {
    fputcsv($fp, $row);
}

fclose($fp);

通过访问包含这段代码的 PHP 文件，浏览器会提示下载一个名为 users.csv 的文件，内容即为我们准备的数据。

五、常见问题与注意事项

字符编码问题：默认输出为 UTF-8，如果在 Excel 中打开出现乱码，可以在输出前加上 UTF-8 BOM 头：
```
echo "\xEF\xBB\xBF"; // 添加 BOM
```
数组必须是一维的：fputcsv() 只接受一维数组，如果你传入多维数组需要逐行处理。
文件权限问题：确保 PHP 脚本有权限写入指定目录，否则 fopen() 会失败。

六、总结

通过 PHP 的 fputcsv() 函数，我们可以非常方便地将数组格式的数据写入 CSV 文件，无论是写入本地文件还是直接通过浏览器下载。只需准备好数据并正确使用文件操作函数，就可以实现高效、规范的数据导出功能。