PHP使用cURL向monday.com API上传文件返回500错误如何解决

云原生阿岚

2026-8-30

问题原因排查

你的代码返回500错误是由3个不符合接口规则的问题导致的：

缺失必填的map表单参数：monday.com文件上传接口遵循GraphQL多部分请求规范，必须通过map字段明确映射上传文件的表单键名到对应GraphQL变量的路径，你的代码完全遗漏该字段，是触发服务端错误的核心原因。
CURLFile传参错误：PHP的CURLFile构造函数仅支持本地文件系统路径，不支持直接传入远程URL，你直接传远程图片链接会导致cURL无法读取文件内容，上传内容为空。
variables参数格式错误：接口要求variables作为独立表单字段传入JSON格式字符串，你错误拆分为variables[file]数组格式，接口无法正常解析参数。

可运行的正确实现代码

<?php
// 基础配置
$apiToken = '替换为你的monday.com API密钥';
$targetItemId = 279111; // 替换为实际目标项ID
$targetColumnId = 'files'; // 替换为实际文件列ID

// 处理待上传文件：远程文件先下载到系统临时目录，本地文件直接填写本地绝对路径即可
$sourceFileUrl = 'https://cdn.pixabay.com/photo/2015/05/26/12/30/baby-784608_960_720.jpg';
$tempLocalPath = tempnam(sys_get_temp_dir(), 'mdy_upload_');
file_put_contents($tempLocalPath, file_get_contents($sourceFileUrl));

$curl = curl_init();
curl_setopt_array($curl, [
    CURLOPT_URL => 'https://api.monday.com/v2/file',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: ' . $apiToken
    ],
    CURLOPT_POSTFIELDS => [
        'query' => 'mutation add_file($file: File!, $item_id: Int!, $column_id: String!) {
            add_file_to_column(file: $file, item_id: $item_id, column_id: $column_id) {
                id
            }
        }',
        'variables' => json_encode([
            'item_id' => $targetItemId,
            'column_id' => $targetColumnId
        ]),
        // 映射文件字段到GraphQL变量路径，键名可自定义，需和下方文件字段名一致
        'map' => json_encode([
            'upload_file' => 'variables.file'
        ]),
        // 上传本地文件
        'upload_file' => new CURLFile(
            $tempLocalPath,
            mime_content_type($tempLocalPath),
            basename($sourceFileUrl)
        )
    ]
]);

$response = curl_exec($curl);
$curlError = curl_error($curl);
curl_close($curl);

// 清理临时文件
unlink($tempLocalPath);

if ($curlError) {
    echo "请求错误：" . $curlError;
} else {
    echo "接口返回：" . $response;
}
?>

注意事项

上传本地文件时，不需要下载到临时目录的步骤，直接将本地文件的绝对路径传入CURLFile即可。
不要手动在请求头中添加Content-Type: multipart/form-data，否则会丢失cURL自动生成的boundary分隔符，导致接口无法解析表单内容。
提前确认API密钥拥有对应看板、项的写入权限，填写的item_id、column_id和实际看板信息匹配，单文件大小不超过平台限制（最大500MB）。
生产环境使用时建议增加远程文件下载失败、本地文件不可读的异常判断逻辑，避免报错。

内容的提问来源于stack exchange，提问作者Nancy Moore