使用 mysqli_stmt::send_long_data 时常见的错误有哪些？如何快速定位和解决？

gitbox 2025-08-16

1. 错误一：send_long_data 的调用顺序不正确

mysqli_stmt::send_long_data 必须在执行语句之前调用。如果你在调用 execute() 之后再尝试使用 send_long_data，则会发生错误。常见的错误信息包括：

Warning: mysqli_stmt::send_long_data() expects parameter 1 to be resource, null given.

这种错误是由于 send_long_data 被调用时，SQL 语句的句柄还没有正确准备好。

解决方法
确保在执行 SQL 语句前先使用 send_long_data 来传递长数据。正确的顺序应该是：

<span><span><span class="hljs-variable">$stmt</span></span><span> = </span><span><span class="hljs-variable">$mysqli</span></span><span>-&gt;</span><span><span class="hljs-title function_ invoke__">prepare</span></span><span>(</span><span><span class="hljs-string">"INSERT INTO large_data (content) VALUES (?)"</span></span><span>);
</span><span><span class="hljs-variable">$stmt</span></span><span>-&gt;</span><span><span class="hljs-title function_ invoke__">bind_param</span></span><span>(</span><span><span class="hljs-string">"s"</span></span><span>, </span><span><span class="hljs-variable">$data</span></span><span>);
</span><span><span class="hljs-variable">$stmt</span></span><span>-&gt;</span><span><span class="hljs-title function_ invoke__">send_long_data</span></span><span>(</span><span><span class="hljs-number">0</span></span><span>, </span><span><span class="hljs-variable">$largeData</span></span><span>);  </span><span><span class="hljs-comment">// 发送大数据</span></span><span>
</span><span><span class="hljs-variable">$stmt</span></span><span>-&gt;</span><span><span class="hljs-title function_ invoke__">execute</span></span><span>();  </span><span><span class="hljs-comment">// 执行语句</span></span><span>
</span></span>

2. 错误二：参数索引不正确

问题描述
send_long_data 需要正确指定参数的索引。例如，如果 SQL 语句中有多个占位符，必须传递正确的参数索引。

Warning: mysqli_stmt::send_long_data() expects parameter 1 to be resource, null given.

该错误通常发生在没有指定正确的索引时，导致 PHP 无法正确定位数据。

解决方法
确保在 send_long_data 中正确指定了索引。索引通常是从 0 开始，表示 SQL 语句中的第一个占位符。例如：

<span><span><span class="hljs-variable">$stmt</span></span><span> = </span><span><span class="hljs-variable">$mysqli</span></span><span>-&gt;</span><span><span class="hljs-title function_ invoke__">prepare</span></span><span>(</span><span><span class="hljs-string">"INSERT INTO large_data (content) VALUES (?)"</span></span><span>);
</span><span><span class="hljs-variable">$stmt</span></span><span>-&gt;</span><span><span class="hljs-title function_ invoke__">bind_param</span></span><span>(</span><span><span class="hljs-string">"s"</span></span><span>, </span><span><span class="hljs-variable">$data</span></span><span>);
</span><span><span class="hljs-variable">$stmt</span></span><span>-&gt;</span><span><span class="hljs-title function_ invoke__">send_long_data</span></span><span>(</span><span><span class="hljs-number">0</span></span><span>, </span><span><span class="hljs-variable">$largeData</span></span><span>);  </span><span><span class="hljs-comment">// 正确传递第一个占位符的长数据</span></span><span>
</span><span><span class="hljs-variable">$stmt</span></span><span>-&gt;</span><span><span class="hljs-title function_ invoke__">execute</span></span><span>();
</span></span>

3. 错误三：数据大小超过 MySQL 配置限制

问题描述
mysqli_stmt::send_long_data 是用来处理大数据的，但如果数据超出了 MySQL 配置中设置的最大数据大小，就会导致传输失败。这通常表现为错误信息：

MySQL Error: Data too long for column.

该错误通常与 max_allowed_packet 参数有关，这是 MySQL 配置文件中的一个选项，控制了单次发送的最大数据包大小。

解决方法
要解决此问题，首先需要检查和调整 MySQL 配置文件中的 max_allowed_packet 参数。你可以通过以下命令查看当前的配置：

<span><span><span class="hljs-keyword">SHOW</span></span><span> VARIABLES </span><span><span class="hljs-keyword">LIKE</span></span><span> </span><span><span class="hljs-string">'max_allowed_packet'</span></span><span>;
</span></span>

如果当前值较小，可以在 my.cnf 或 my.ini 文件中增加该参数的值，然后重启 MySQL 服务：

<span><span><span class="hljs-attr">max_allowed_packet</span></span><span> = </span><span><span class="hljs-number">64</span></span><span>M
</span></span>

4. 错误四：数据类型不匹配

问题描述
send_long_data 用于发送长数据时，必须保证传递的数据类型和 SQL 语句中占位符的类型相匹配。例如，如果占位符类型为 BLOB，则传递的数据必须是二进制数据。

如果数据类型不匹配，可能会导致错误，例如：

Warning: mysqli_stmt::send_long_data() expects parameter 2 to be string, resource given.

解决方法
确保传递的数据类型与 SQL 语句中的占位符类型一致。如果占位符类型是字符串（s），数据应该是字符串；如果是二进制数据（b），数据应该是二进制格式。

<span><span><span class="hljs-variable">$stmt</span></span><span> = </span><span><span class="hljs-variable">$mysqli</span></span><span>-&gt;</span><span><span class="hljs-title function_ invoke__">prepare</span></span><span>(</span><span><span class="hljs-string">"INSERT INTO large_data (file_content) VALUES (?)"</span></span><span>);
</span><span><span class="hljs-variable">$stmt</span></span><span>-&gt;</span><span><span class="hljs-title function_ invoke__">bind_param</span></span><span>(</span><span><span class="hljs-string">"b"</span></span><span>, </span><span><span class="hljs-variable">$binaryData</span></span><span>);
</span><span><span class="hljs-variable">$stmt</span></span><span>-&gt;</span><span><span class="hljs-title function_ invoke__">send_long_data</span></span><span>(</span><span><span class="hljs-number">0</span></span><span>, </span><span><span class="hljs-variable">$binaryData</span></span><span>);  </span><span><span class="hljs-comment">// 发送二进制数据</span></span><span>
</span><span><span class="hljs-variable">$stmt</span></span><span>-&gt;</span><span><span class="hljs-title function_ invoke__">execute</span></span><span>();
</span></span>

5. 错误五：连接未保持活跃或超时

问题描述
send_long_data 需要保持活跃的数据库连接，如果在执行过程中连接超时或被关闭，会导致错误。错误信息可能为：

Error: Lost connection to MySQL server during query.

这个问题通常发生在长时间未操作数据库时，或者在上传大量数据时连接被中断。

解决方法
为避免连接超时，确保数据库连接在操作期间保持活跃。如果数据传输时间较长，可以通过调整 PHP 的 max_execution_time 或者 MySQL 的 wait_timeout 来避免超时。

<span><span><span class="hljs-title function_ invoke__">ini_set</span></span><span>(</span><span><span class="hljs-string">'max_execution_time'</span></span><span>, </span><span><span class="hljs-number">300</span></span><span>);  </span><span><span class="hljs-comment">// PHP 最大执行时间 5 分钟</span></span><span>
</span></span>

同时，也可以考虑在发送大量数据时，分批次进行处理，以避免一次性发送过多数据导致连接丢失。

6. 错误六：未正确绑定参数

问题描述
在执行 SQL 语句时，必须正确绑定所有的参数。如果绑定参数时出现错误，可能会导致 send_long_data 无法正常工作。例如，如果使用了 bind_param 绑定参数，但数据没有成功传递，就会出现问题。

解决方法
确保在执行 SQL 语句之前，使用 bind_param 正确绑定所有必要的参数，并检查返回值以确认绑定是否成功。

<span><span><span class="hljs-variable">$stmt</span></span><span> = </span><span><span class="hljs-variable">$mysqli</span></span><span>-&gt;</span><span><span class="hljs-title function_ invoke__">prepare</span></span><span>(</span><span><span class="hljs-string">"INSERT INTO large_data (content) VALUES (?)"</span></span><span>);
</span><span><span class="hljs-variable">$stmt</span></span><span>-&gt;</span><span><span class="hljs-title function_ invoke__">bind_param</span></span><span>(</span><span><span class="hljs-string">"s"</span></span><span>, </span><span><span class="hljs-variable">$data</span></span><span>);
</span><span><span class="hljs-keyword">if</span></span><span> (</span><span><span class="hljs-variable">$stmt</span></span><span>-&gt;</span><span><span class="hljs-title function_ invoke__">execute</span></span><span>()) {
    </span><span><span class="hljs-variable">$stmt</span></span><span>-&gt;</span><span><span class="hljs-title function_ invoke__">send_long_data</span></span><span>(</span><span><span class="hljs-number">0</span></span><span>, </span><span><span class="hljs-variable">$largeData</span></span><span>);  </span><span><span class="hljs-comment">// 确保在绑定参数后再发送长数据</span></span><span>
}
</span></span>

相关标签:
mysqli_stmt

mysqli_stmt::send_long_data