本文详细介绍了如何使用 php curl 通过 discord webhook 发送文件附件。重点阐述了 `curl_file_create` 函数的正确用法，特别是 `realpath()` 在指定文件路径时的重要性，并提供了处理本地文件和远程文件上传的完整代码示例及注意事项，帮助开发者解决文件上传过程中遇到的常见问题。
理解 Discord Webhook 文件上传机制
Discord Webhook 支持通过 multipart/form-data 编码方式发送文件附件。这意味着在发送 POST 请求时，除了消息内容、用户名等字段外，还可以包含一个或多个文件字段。在 PHP 中，我们通常使用 cURL 库来构建和发送此类请求。
使用 PHP cURL 上传本地文件
在尝试使用 cURL 上传本地文件时，一个常见的错误是文件路径不正确，导致 Discord API 返回 "Cannot send an empty message" 的错误。这是因为 cURL 无法找到或读取指定的文件，从而导致文件部分为空。
常见问题代码示例：
<?php
$url = "YOUR_WEBHOOK_URL_HERE"; // 替换为你的 Discord Webhook URL
$headers = [ 'Content-Type: multipart/form-data; charset=utf-8' ];
$POST = [
"content" => "Hello World! 这是一个测试附件。",
"username" => "测试用户",
// 文件上传，这里可能存在路径问题
"file" => curl_file_create("image.gif", 'image/gif', 'image')
];
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false); // 在生产环境中应设为 true
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($POST)); // 注意：这里是错误的用法
$response = curl_exec($ch);
var_dump($response);
curl_close($ch);上述代码中，http_build_query($POST) 会将 curl_file_create 对象序列化为字符串，而非 multipart/form-data 所需的正确格式。此外，curl_file_create("image.gif", ...) 如果文件不在当前脚本的执行路径下，cURL 将无法找到该文件。
立即学习“PHP免费学习笔记（深入）”；
正确的文件路径处理与请求构建：
解决文件路径问题，关键在于使用 realpath() 函数来获取文件的绝对路径。realpath() 函数能够将相对路径转换为绝对路径，确保 cURL 能够准确找到文件。同时，对于 multipart/form-data 请求，CURLOPT_POSTFIELDS 应该直接接收包含 curl_file_create 对象的数组，cURL 会自动处理其编码。
修正后的代码示例：
<?php
$url = "YOUR_WEBHOOK_URL_HERE"; // 替换为你的 Discord Webhook URL
// 确保文件存在且路径正确
$filePath = realpath("image.gif");
if (!$filePath) {
die("Error: File 'image.gif' not found or inaccessible.");
}
$POST = [
// 消息内容
"content" => "Hello World! 这是一个测试附件。",
// 用户名
"username" => "测试用户",
// 文件上传
// realpath() 确保文件路径是绝对的
// 'image.gif' 是在 Discord 上显示的文件名
"file" => curl_file_create($filePath, 'image/gif', 'image.gif')
];
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, true);
// 对于 multipart/form-data，当 CURLOPT_POSTFIELDS 接收数组时，cURL 会自动设置正确的 Content-Type 头
// 所以通常不需要手动设置 'Content-Type: multipart/form-data'
// 如果手动设置，确保没有 charset=utf-8，因为 cURL 会自动添加 boundary
// $headers = [ 'Content-Type: multipart/form-data' ];
// curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true); // 生产环境建议保持为 true
curl_setopt($ch, CURLOPT_POSTFIELDS, $POST); // 直接传递数组，cURL 会自动处理 multipart/form-data
$response = curl_exec($ch);
if (curl_errno($ch)) {
echo 'cURL Error: ' . curl_error($ch);
} else {
var_dump($response);
}
curl_close($ch);curl_file_create 参数说明：
- $filename: 文件的完整路径，建议使用 realpath() 确保其绝对性。
- $mimetype: 文件的 MIME 类型（例如 image/gif, application/pdf, text/plain）。
- $postname: 在 Discord 上显示的文件名。
处理远程 URL 文件上传
Discord Webhook 不支持直接从一个外部 URL 拉取文件进行上传。如果你的文件存储在一个远程服务器上，你需要先将该文件下载到你的本地服务器（作为临时文件），然后再按照上述方法将这个临时文件上传到 Discord。
远程文件上传流程：
- 从远程 URL 下载文件内容。
- 将文件内容保存到本地服务器的临时文件。
- 使用 curl_file_create 上传这个临时文件。
- 上传完成后，删除本地的临时文件。
代码示例：
<?php
$url = "YOUR_WEBHOOK_URL_HERE"; // 替换为你的 Discord Webhook URL
$remoteFileUrl = "https://example.com/path/to/remote/image.gif"; // 远程文件 URL
// 1. 下载远程文件到本地临时文件
$tempFileName = tempnam(sys_get_temp_dir(), 'discord_upload_'); // 创建一个唯一的临时文件名
$tempFileHandle = fopen($tempFileName, 'w');
$remoteCh = curl_init($remoteFileUrl);
curl_setopt($remoteCh, CURLOPT_FILE, $tempFileHandle); // 将输出写入文件句柄
curl_setopt($remoteCh, CURLOPT_HEADER, 0);
curl_setopt($remoteCh, CURLOPT_FOLLOWLOCATION, true); // 遵循重定向
curl_setopt($remoteCh, CURLOPT_SSL_VERIFYPEER, true);
curl_exec($remoteCh);
$httpCode = curl_getinfo($remoteCh, CURLINFO_HTTP_CODE);
curl_close($remoteCh);
fclose($tempFileHandle);
if ($httpCode !== 200) {
unlink($tempFileName); // 下载失败，删除临时文件
die("Error: Failed to download remote file. HTTP Code: " . $httpCode);
}
// 2. 准备上传到 Discord
$POST = [
"content" => "这是一个从远程 URL 上传的附件。",
"username" => "远程文件上传器",
// 使用临时文件的真实路径和原始文件名
"file" => curl_file_create(realpath($tempFileName), 'image/gif', 'remote_image.gif')
];
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $POST);
$response = curl_exec($ch);
if (curl_errno($ch)) {
echo 'cURL Error: ' . curl_error($ch);
} else {
var_dump($response);
}
curl_close($ch);
// 3. 删除临时文件
unlink($tempFileName);
echo "Temporary file " . $tempFileName . " deleted.\n";
?>注意事项与最佳实践
- 文件路径准确性： 始终使用 realpath() 来确保文件路径的绝对性和正确性，避免因相对路径问题导致文件找不到。
- CURLOPT_POSTFIELDS： 当发送 multipart/form-data 请求时，CURLOPT_POSTFIELDS 应该直接传入包含 curl_file_create 对象的数组，cURL 会自动处理正确的编码和 Content-Type 头。
- 错误处理： 务必检查 curl_exec() 的返回值以及 curl_errno() 和 curl_error() 来捕获 cURL 级别的错误。同时，解析 Discord API 的响应（通常是 JSON 格式）来检查是否有 API 级别的错误信息（如 {"message": "...", "code": ...}）。
- 临时文件管理： 如果从远程 URL 下载文件，确保在上传完成后及时删除本地生成的临时文件，以避免磁盘空间浪费和潜在的安全风险。
- 文件类型与大小限制： Discord 对上传的文件类型和大小有限制。请查阅 Discord 开发者文档以获取最新的限制信息。如果文件过大，可能需要考虑其他上传方式或压缩文件。
- SSL 验证： 在生产环境中，CURLOPT_SSL_VERIFYPEER 务必设置为 true，以确保数据传输的安全性。
- Webhook URL 安全： Discord Webhook URL 包含敏感信息，不应在客户端代码中硬编码或公开。
通过遵循这些指导原则和代码示例，你可以有效地使用 PHP cURL 向 Discord Webhook 发送文件附件，无论是本地文件还是来自远程 URL 的文件。
