curl 命令--data-binary完全指南按原样 POST 二进制数据、保留换行与空字节的底层原理【免费下载链接】curlA command line tool and library for transferring data with URL syntax, supporting DICT, FILE, FTP, FTPS, GOPHER, GOPHERS, HTTP, HTTPS, IMAP, IMAPS, LDAP, LDAPS, MQTT, MQTTS, POP3, POP3S, RTSP, SCP, SFTP, SMB, SMBS, SMTP, SMTPS, TELNET, TFTP, WS and WSS. libcurl offers a myriad of powerful features项目地址: https://gitcode.com/GitHub_Trending/cu/curl--data-binary是 curl命令行工具与 libcurl 传输库用于 HTTP POST 时按字节原样提交数据的关键选项它不做任何额外加工、不剥离换行与回车、也不过滤空字节。本文以仓库中该选项的官方说明 docs/cmdline-opts/data-binary.md 为骨架结合 curl 源码中的参数解析链路为你梳理它的语法、与--data/--data-raw/--data-urlencode的取舍、Content-Type 设置技巧以及数据如何从命令行进入请求体的实现细节。选项速览--data-binary是什么在 curl 中所有以--data开头的系列选项都用于向服务器发送数据。--data-binary的官方定义极其精简却也点出了它与其他选项最本质的差异Post data exactly as specified with no extra processing whatsoever. 完全按给定内容发送数据不做任何额外处理。从该选项的元数据定义见 docs/cmdline-opts/data-binary.md 开头的 front-matter可以得到如下事实表属性取值说明长选项--data-binary无短选项别名参数data数据本体或filename/-帮助文本HTTP POST binary data工具内置帮助同样如此描述适用协议HTTP与--dataHTTP MQTT不同仅限 HTTP分类http post upload属于 HTTP 表单提交 / 上传家族引入版本7.2相当古老的选项早已是稳定行为Multi 属性append可重复使用多次指定的数据会拼接curl 命令行工具内置的帮助列表也做了同步维护可在 src/tool_listhelp.c 中看到--data-binary data的条目。核心差异什么叫做不做任何额外处理理解--data-binary的最好方式是与同族的其他选项对照。curl 对前缀和换行/空字节的处理在各选项间并不一致这正是选择--data-binary的真正理由。与--data的对比保留换行、回车与二进制官方文档>curl --data-binary filename $URL一个更接近真实用途的示例——上传 JSON 文件并显式声明媒体类型curl --data-binary data.json \ -H Content-Type: application/json \ https://api.example.com/v1/ingestContent-Type默认表单编码如何切换为任意二进制与--data相同--data-binary默认发送给服务器的 Content-Type 是application/x-www-form-urlencoded。这是历史兼容行为意味着如果你不额外指定头服务器即便收到的是二进制内容也会先按 URL 编码表单来理解请求体。如果你希望服务器把数据当作**任意二进制arbitrary binary data**处理文档给出的做法是显式覆盖该请求头curl --data-binary blob.bin \ -H Content-Type: application/octet-stream \ https://upload.example.com/raw实际项目中也常出现Content-Type: application/json、application/pdf、application/x-protobuf等覆盖写法原理一致-H中显式声明的 Content-Type 会覆盖选项内置的默认值。多次使用的拼接语义Multi: append选项元数据中的Multi: append意味着--data-binary可以重复出现并且数据会按顺序累积。拼接规则继承自--datadocs/cmdline-opts/data.md 有完整描述If any of these options is used more than once on the same command line, the data pieces specified are merged with a separating -symbol. Thus, using-d namedaniel -d skilllousywould generate a post chunk that looks likenamedanielskilllousy.翻译成--data-binary的等价行为# 最终请求体等价于 namedanielskilllousy curl --data-binary namedaniel --data-binary skilllousy $URL这个拼接对表单拼接很友好但对二进制文件分块投递不友好如果一段二进制数据里恰好含有字节拼接语义仍会原样保留它--data-binary不会改写你的字节只是在多次指定时curl 会在两段数据之间主动插入一个。因此需要投递单个完整二进制文件的场景请只使用一次--data-binary file不要拆成多段。源码级原理从命令行参数到请求体的调用链步骤一参数表注册在命令行解析器 src/tool_getparam.c 中--data-binary被注册为无短选项、参数类型为字符串的选项并映射到内部枚举C_DATA_BINARY{data-binary, ARG_STRG, , C_DATA_BINARY},步骤二统一分发到 set_data()在 src/tool_getparam.c 处--data、--data-ascii、--data-binary、--data-urlencode、--json、--data-raw全部汇入同一个处理函数set_data()这正是各选项行为相近、仅在细节上分野的原因。步骤三前缀与文件读取分支核心逻辑位于 src/tool_getparam.c 的set_data()else if( *nextarg (cmd ! C_DATA_RAW)) { /* the data begins with a letter, it means that a filename or - (stdin) follows */ nextarg; /* pass the */ ... if(cmd C_DATA_BINARY) /* forced>if(curlx_dyn_len(config-postdata)) { if(!err (cmd ! C_JSON) curlx_dyn_addn(config-postdata, , 1)) err PARAM_NO_MEM; } ... config-postfields curlx_dyn_ptr(config-postdata);这段代码从实现层面印证了多次使用以拼接的文档语义也解释了为什么--json不参与拼接JSON 载荷不适用表单分隔符。累积完成的config-postfields指针随后会被传给 libcurl 的传输层选项CURLOPT_POSTFIELDS/CURLOPT_COPYPOSTFIELDS其接收逻辑位于库侧 lib/setopt.c配合 lib/setopt.c 处的CURLOPT_POSTFIELDSIZE_LARGE一起libcurl 才能真正按字节长度而非strlen发送含空字节的二进制请求体。调用链小结--data-binary file → src/tool_getparam.c 选项表 (C_DATA_BINARY) → getparameter() 分发 (case C_DATA_BINARY) → set_data() ├─ 判定 → rb 打开文件 / 对 stdin 置二进制模式 ├─ file2memory() → 完整保留换行/回车/空字节 └─ dynbuf postdata 累积多次指定时插入 → config-postfields → libcurl CURLOPT_POSTFIELDS / CURLOPT_POSTFIELDSIZE (lib/setopt.c) → HTTP POST 请求体实用示例集合把上面的规则串起来下面这些命令都值得收藏1. 从文件原样提交文本/JSON保留所有换行缩进curl --data-binary payload.json \ -H Content-Type: application/json \ https://httpbin.org/post2. 提交任意二进制并告知服务器为字节流curl --data-binary model.bin \ -H Content-Type: application/octet-stream \ https://upload.example.com/files3. 从标准输入管道读取cat screenshot.png | curl --data-binary - \ -H Content-Type: application/octet-stream \ https://upload.example.com/images4. 直接内联 POST 二进制安全的字符串curl --data-binary line1 line2 https://example.com/echo注意内联模式下换行由 shell 引号内的真实换行决定curl 原样发送。注意事项与易错点协议范围仅为 HTTP--data-binary的协议标记是 HTTP而--data还支持 MQTT数据以 PUBLISH 语义发送。涉及 MQTT 的载荷请使用--data家族而非--data-binary。二进制文件请单次指定多次使用会插入分隔可能污染二进制流。空字节需要配合正确的 Content-Type 与接收方默认application/x-www-form-urlencoded下服务器可能拒绝或误解析请显式覆盖请求头。冲突如果待投递内容本身以开头且不想触发文件读取请改选--data-raw它放弃解释也不保留读文件路径如果必须从文件读取--data-binary是正确选择。使用场景判断需保留换行、回车的文本如格式化 JSON、多行报文以及含空字节的任意二进制图片、压缩包、序列化数据都是--data-binary的典型适用面普通键值对表单则优先--data/--data-urlencode。延伸阅读官方选项说明docs/cmdline-opts/data-binary.md同族选项docs/cmdline-opts/data.md、docs/cmdline-opts/data-raw.md、docs/cmdline-opts/data-ascii.md、docs/cmdline-opts/data-urlencode.md命令行解析实现src/tool_getparam.c内嵌帮助文本生成src/tool_listhelp.clibcurl 侧请求体选项处理lib/setopt.c【免费下载链接】curlA command line tool and library for transferring data with URL syntax, supporting DICT, FILE, FTP, FTPS, GOPHER, GOPHERS, HTTP, HTTPS, IMAP, IMAPS, LDAP, LDAPS, MQTT, MQTTS, POP3, POP3S, RTSP, SCP, SFTP, SMB, SMBS, SMTP, SMTPS, TELNET, TFTP, WS and WSS. libcurl offers a myriad of powerful features项目地址: https://gitcode.com/GitHub_Trending/cu/curl创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 curl 命令 `--data-binary` 完全指南：按原样 POST 二进制数据、保留换行与空字节的底层原理
curl 命令--data-binary完全指南按原样 POST 二进制数据、保留换行与空字节的底层原理【免费下载链接】curlA command line tool and library for transferring data with URL syntax, supporting DICT, FILE, FTP, FTPS, GOPHER, GOPHERS, HTTP, HTTPS, IMAP, IMAPS, LDAP, LDAPS, MQTT, MQTTS, POP3, POP3S, RTSP, SCP, SFTP, SMB, SMBS, SMTP, SMTPS, TELNET, TFTP, WS and WSS. libcurl offers a myriad of powerful features项目地址: https://gitcode.com/GitHub_Trending/cu/curl--data-binary是 curl命令行工具与 libcurl 传输库用于 HTTP POST 时按字节原样提交数据的关键选项它不做任何额外加工、不剥离换行与回车、也不过滤空字节。本文以仓库中该选项的官方说明 docs/cmdline-opts/data-binary.md 为骨架结合 curl 源码中的参数解析链路为你梳理它的语法、与--data/--data-raw/--data-urlencode的取舍、Content-Type 设置技巧以及数据如何从命令行进入请求体的实现细节。选项速览--data-binary是什么在 curl 中所有以--data开头的系列选项都用于向服务器发送数据。--data-binary的官方定义极其精简却也点出了它与其他选项最本质的差异Post data exactly as specified with no extra processing whatsoever. 完全按给定内容发送数据不做任何额外处理。从该选项的元数据定义见 docs/cmdline-opts/data-binary.md 开头的 front-matter可以得到如下事实表属性取值说明长选项--data-binary无短选项别名参数data数据本体或filename/-帮助文本HTTP POST binary data工具内置帮助同样如此描述适用协议HTTP与--dataHTTP MQTT不同仅限 HTTP分类http post upload属于 HTTP 表单提交 / 上传家族引入版本7.2相当古老的选项早已是稳定行为Multi 属性append可重复使用多次指定的数据会拼接curl 命令行工具内置的帮助列表也做了同步维护可在 src/tool_listhelp.c 中看到--data-binary data的条目。核心差异什么叫做不做任何额外处理理解--data-binary的最好方式是与同族的其他选项对照。curl 对前缀和换行/空字节的处理在各选项间并不一致这正是选择--data-binary的真正理由。与--data的对比保留换行、回车与二进制官方文档>curl --data-binary filename $URL一个更接近真实用途的示例——上传 JSON 文件并显式声明媒体类型curl --data-binary data.json \ -H Content-Type: application/json \ https://api.example.com/v1/ingestContent-Type默认表单编码如何切换为任意二进制与--data相同--data-binary默认发送给服务器的 Content-Type 是application/x-www-form-urlencoded。这是历史兼容行为意味着如果你不额外指定头服务器即便收到的是二进制内容也会先按 URL 编码表单来理解请求体。如果你希望服务器把数据当作**任意二进制arbitrary binary data**处理文档给出的做法是显式覆盖该请求头curl --data-binary blob.bin \ -H Content-Type: application/octet-stream \ https://upload.example.com/raw实际项目中也常出现Content-Type: application/json、application/pdf、application/x-protobuf等覆盖写法原理一致-H中显式声明的 Content-Type 会覆盖选项内置的默认值。多次使用的拼接语义Multi: append选项元数据中的Multi: append意味着--data-binary可以重复出现并且数据会按顺序累积。拼接规则继承自--datadocs/cmdline-opts/data.md 有完整描述If any of these options is used more than once on the same command line, the data pieces specified are merged with a separating -symbol. Thus, using-d namedaniel -d skilllousywould generate a post chunk that looks likenamedanielskilllousy.翻译成--data-binary的等价行为# 最终请求体等价于 namedanielskilllousy curl --data-binary namedaniel --data-binary skilllousy $URL这个拼接对表单拼接很友好但对二进制文件分块投递不友好如果一段二进制数据里恰好含有字节拼接语义仍会原样保留它--data-binary不会改写你的字节只是在多次指定时curl 会在两段数据之间主动插入一个。因此需要投递单个完整二进制文件的场景请只使用一次--data-binary file不要拆成多段。源码级原理从命令行参数到请求体的调用链步骤一参数表注册在命令行解析器 src/tool_getparam.c 中--data-binary被注册为无短选项、参数类型为字符串的选项并映射到内部枚举C_DATA_BINARY{data-binary, ARG_STRG, , C_DATA_BINARY},步骤二统一分发到 set_data()在 src/tool_getparam.c 处--data、--data-ascii、--data-binary、--data-urlencode、--json、--data-raw全部汇入同一个处理函数set_data()这正是各选项行为相近、仅在细节上分野的原因。步骤三前缀与文件读取分支核心逻辑位于 src/tool_getparam.c 的set_data()else if( *nextarg (cmd ! C_DATA_RAW)) { /* the data begins with a letter, it means that a filename or - (stdin) follows */ nextarg; /* pass the */ ... if(cmd C_DATA_BINARY) /* forced>if(curlx_dyn_len(config-postdata)) { if(!err (cmd ! C_JSON) curlx_dyn_addn(config-postdata, , 1)) err PARAM_NO_MEM; } ... config-postfields curlx_dyn_ptr(config-postdata);这段代码从实现层面印证了多次使用以拼接的文档语义也解释了为什么--json不参与拼接JSON 载荷不适用表单分隔符。累积完成的config-postfields指针随后会被传给 libcurl 的传输层选项CURLOPT_POSTFIELDS/CURLOPT_COPYPOSTFIELDS其接收逻辑位于库侧 lib/setopt.c配合 lib/setopt.c 处的CURLOPT_POSTFIELDSIZE_LARGE一起libcurl 才能真正按字节长度而非strlen发送含空字节的二进制请求体。调用链小结--data-binary file → src/tool_getparam.c 选项表 (C_DATA_BINARY) → getparameter() 分发 (case C_DATA_BINARY) → set_data() ├─ 判定 → rb 打开文件 / 对 stdin 置二进制模式 ├─ file2memory() → 完整保留换行/回车/空字节 └─ dynbuf postdata 累积多次指定时插入 → config-postfields → libcurl CURLOPT_POSTFIELDS / CURLOPT_POSTFIELDSIZE (lib/setopt.c) → HTTP POST 请求体实用示例集合把上面的规则串起来下面这些命令都值得收藏1. 从文件原样提交文本/JSON保留所有换行缩进curl --data-binary payload.json \ -H Content-Type: application/json \ https://httpbin.org/post2. 提交任意二进制并告知服务器为字节流curl --data-binary model.bin \ -H Content-Type: application/octet-stream \ https://upload.example.com/files3. 从标准输入管道读取cat screenshot.png | curl --data-binary - \ -H Content-Type: application/octet-stream \ https://upload.example.com/images4. 直接内联 POST 二进制安全的字符串curl --data-binary line1 line2 https://example.com/echo注意内联模式下换行由 shell 引号内的真实换行决定curl 原样发送。注意事项与易错点协议范围仅为 HTTP--data-binary的协议标记是 HTTP而--data还支持 MQTT数据以 PUBLISH 语义发送。涉及 MQTT 的载荷请使用--data家族而非--data-binary。二进制文件请单次指定多次使用会插入分隔可能污染二进制流。空字节需要配合正确的 Content-Type 与接收方默认application/x-www-form-urlencoded下服务器可能拒绝或误解析请显式覆盖请求头。冲突如果待投递内容本身以开头且不想触发文件读取请改选--data-raw它放弃解释也不保留读文件路径如果必须从文件读取--data-binary是正确选择。使用场景判断需保留换行、回车的文本如格式化 JSON、多行报文以及含空字节的任意二进制图片、压缩包、序列化数据都是--data-binary的典型适用面普通键值对表单则优先--data/--data-urlencode。延伸阅读官方选项说明docs/cmdline-opts/data-binary.md同族选项docs/cmdline-opts/data.md、docs/cmdline-opts/data-raw.md、docs/cmdline-opts/data-ascii.md、docs/cmdline-opts/data-urlencode.md命令行解析实现src/tool_getparam.c内嵌帮助文本生成src/tool_listhelp.clibcurl 侧请求体选项处理lib/setopt.c【免费下载链接】curlA command line tool and library for transferring data with URL syntax, supporting DICT, FILE, FTP, FTPS, GOPHER, GOPHERS, HTTP, HTTPS, IMAP, IMAPS, LDAP, LDAPS, MQTT, MQTTS, POP3, POP3S, RTSP, SCP, SFTP, SMB, SMBS, SMTP, SMTPS, TELNET, TFTP, WS and WSS. libcurl offers a myriad of powerful features项目地址: https://gitcode.com/GitHub_Trending/cu/curl创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考