cpp-httplib 下载响应实战：用 Content-Disposition 实现文件下载与动态导出

本篇指南基于 cpp-httplib 官方 Cookbook 的 S06 章节，讲解如何在 C++ 单头文件 HTTP 服务器中返回"下载响应"：通过 Content-Disposition 响应头强制浏览器弹出"另存为"对话框，覆盖静态文件下载、非 ASCII 文件名的 RFC 5987 编码，以及无需真实文件的内存数据（如 CSV）直接导出等场景，并深入 httplib.h 源码解析 set_file_content / set_content 的底层实现与进阶行为。阅读本文后，你可以为自己的服务端路由添加标准、健壮且兼容旧浏览器的文件下载与导出能力。

下载响应的本质：它只是一个响应头

在 cpp-httplib 中并没有任何"下载专用 API"。强制浏览器下载的核心机制是 HTTP 标准响应头 Content-Disposition：

Content-Disposition: attachment; filename="report.pdf"

其中：

• attachment 告诉浏览器不要内联渲染（比如 PDF 不要直接打开、HTML 不要显示成页面），而是弹出"Save As"对话框；
• filename="..." 指定对话框中的默认保存文件名。

正如官方文档 s06-download-response.md 所言："There's no special cpp-httplib API for this — it's just a header." 你只需要调用 Response::set_header 写入该头，其余部分与普通响应完全一致。

set_header 的实现在 httplib.h 中，它将键值对写入 Response::headers 这一 Headers 多值映射容器，并在后续序列化响应行与头部时统一发送（见 httplib.h 的 write_response_line / header_writer_ 调用）。

基本用法：将真实文件作为下载返回

最常见的场景是把磁盘上的文件强制交给用户下载：

svr.Get("/download/report", [](const httplib::Request &req, httplib::Response &res) {
  res.set_header("Content-Disposition", "attachment; filename=\"report.pdf\"");
  res.set_file_content("reports/2026-04.pdf", "application/pdf");
});

关键点：

• set_header 设置 Content-Disposition，attachment 触发下载对话框，filename= 成为默认保存名；
• set_file_content(path, content_type) 声明响应体来自指定文件。该重载在 httplib.h 声明，实现位于 httplib.h：它不会立即读取文件，而是把路径和 Content-Type 暂存在 file_content_path_ 与 file_content_content_type_ 私有成员中，真正的读取发生在服务器写出响应时。

自动推断 MIME 类型

set_file_content 还有一个单参数重载（httplib.h），只传路径。此时服务器会根据文件扩展名在 file_extension_and_mimetype_map_ 中自动查找 Content-Type，找不到则回退到 default_file_mimetype_（默认 application/octet-stream），见 httplib.h。如果你希望自行控制 MIME（例如 PDF 固定为 application/pdf），使用带 Content-Type 参数的重载更稳妥。

文件打开失败的兜底行为

从源码看（httplib.h），当 file_content_path_ 非空时，服务器会尝试用 detail::mmap 打开该文件：

• 打开失败：清空响应体，状态码置为 404 Not Found，并记录 Error::OpenFile 错误日志；
• 打开成功：将文件包装为"文件内容提供者"（content provider），再交由统一的响应写出流程处理。

因此你不需要在路由回调里手动判断文件是否存在——404 由库自动生成，与 cpp-httplib 静态文件服务（set_mount_point）的错误语义保持一致。

非 ASCII 文件名：RFC 5987 filename*

filename="report.pdf" 只能安全承载 ASCII 文件名。如果默认保存名包含中文、日文、空格等非 ASCII 字符，就必须使用 RFC 5987 定义的 filename* 扩展形式：filename*=UTF-8''<URL 编码后的 UTF-8 字节>。

官方文档给出的示例（日文"レポート.pdf"）：

svr.Get("/download/report", [](const httplib::Request &req, httplib::Response &res) {
  res.set_header(
    "Content-Disposition",
    "attachment; filename=\"report.pdf\"; "
    "filename*=UTF-8''%E3%83%AC%E3%83%9D%E3%83%BC%E3%83%88.pdf");
  res.set_file_content("reports/2026-04.pdf", "application/pdf");
});

要点：

• filename*=UTF-8'' 之后的 %E3%83%AC%E3%83%9D%E3%83%BC%E3%83%88.pdf 是 "レポート.pdf" 的 URL 编码 UTF-8 表示；
• 务必同时保留 ASCII 的 filename= 作为回退：部分旧浏览器不识别 filename*，会退回使用 filename= 中的 ASCII 名；现代浏览器优先采用 filename*。

需要说明的是，cpp-httplib 只负责把你拼好的头原样发送，不会替你进行 UTF-8 编码或百分号转义——URL 编码需要由应用层完成。编码逻辑通常为：将文件名的 UTF-8 字节逐个转成 %XX 十六进制形式，空格可编码为 %20。

下载动态生成的数据：CSV 导出

并非所有下载都必须对应磁盘文件。cpp-httplib 的 set_content 允许直接以内存字符串作为响应体，这是 CSV / JSON 导出等"按需生成"场景的经典模式：

svr.Get("/export.csv", [](const httplib::Request &req, httplib::Response &res) {
  std::string csv = build_csv();
  res.set_header("Content-Disposition", "attachment; filename=\"export.csv\"");
  res.set_content(csv, "text/csv");
});

build_csv() 可以是任意业务逻辑（查数据库、聚合统计、拼装报表），生成的字符串被完整复制进响应体后随响应发出。

set_content 的底层行为

set_content 有 3 个重载（httplib.h）：

void set_content(const char *s, size_t n, const std::string &content_type);
void set_content(const std::string &s, const std::string &content_type);
void set_content(std::string &&s, const std::string &content_type);

其实现（httplib.h）值得注意：

• 数据写入 Response::body（右值重载使用 std::move 避免拷贝，适合大字符串）；
• 会先清空已有的 Content-Type 头再写入你传入的类型，避免出现重复的 Content-Type；
• 将 content_coding_ 重置为 None，确保与后续可能的压缩逻辑不冲突。

所以在动态导出场景中，set_content(csv, "text/csv") 与 set_header("Content-Type", "text/csv") 是等价的，但前者更安全（幂等地覆盖旧值）。

关于 Content-Length

对于 set_content 方式，服务器在写出响应时会根据 body 大小自动生成 Content-Length（见 httplib.h：body 非空且已有 Content-Type 时，长度由发送路径计算），客户端因此能显示确切的下载进度条。

从源码看响应写出路径：小文件合并、大文件流式

理解"下载响应"的完整生命周期，还需要知道响应体是如何被发送的。在 write_response_with_content 中（httplib.h）：

• 小文件（小于 CPPHTTPLIB_SEND_BUFSIZ）：文件内容会被读入与响应头同一个缓冲区，与状态行、头部一起一次 write 发出，减少系统调用；
• 大文件 / 普通 content provider：头部先发出，随后由 write_content_with_provider 流式分块写入（httplib.h），配合 mmap 内存映射避免把整个文件载入内存；
• HEAD 请求：send_body 为 false，只发送头部，不发送正文（httplib.h），下载链接的探活与断点续传探测因此天然可用。

也就是说，无论下载的是 1 KB 的小配置文件还是数 GB 的备份文件，cpp-httplib 都能正确处理：小文件低延迟合并发送，大文件内存友好地流式输出。

进阶：下载与大文件的 Range / 压缩交互

当下载响应走的是文件 content provider 时，cpp-httplib 还会自动与以下特性协同：

• Range 请求（断点续传）：服务器在处理响应时会调用 apply_ranges（httplib.h），对带 Range 头的请求返回 206 Partial Content 并切片输出；Content-Length 按 206 语义计算（httplib.h）。因此你的下载路由天然支持下载管理器断点续传，无需额外代码。
• Content-Encoding 压缩：static_file_encoding（httplib.h）会根据请求的 Accept-Encoding 为文件选择 gzip / brotli / zstd 等编码（需在编译时开启对应支持），并保证头部与正文的编码一致。
• Content-Type 默认值：如果 body 存在且路由未设置 Content-Type，服务器会兜底为 text/plain（httplib.h）。因此下载路由请始终显式指定 MIME，避免出现误导性的 text/plain。

注意事项与最佳实践

1. 并非所有浏览器都依赖 Content-Disposition：官方文档明确提示，部分浏览器仅凭 Content-Type（如 application/octet-stream）就会触发下载；反过来，若把值设为 inline，浏览器会尽可能内联渲染内容。因此：
   • 想要"一定弹下载框"，务必显式写 attachment；
   • 想要"能内联就内联"，可省略 Content-Disposition 或写 inline。
2. 非 ASCII 文件名双轨发送：filename* 与 filename= 同时提供，新老浏览器都能得到可读的默认保存名；文件名中如有引号或反斜杠需按 RFC 6266 转义。
3. 路径安全：传给 set_file_content 的是服务器本地路径，注意不要直接把用户输入拼进路径；库内部的静态文件路由会通过 is_valid_path 拦截 .. 目录穿越（httplib.h），但自建下载路由仍应由应用层做权限与路径校验。
4. 组合使用：下载响应可与其他 Cookbook 主题自由组合，例如通过 s05-stream-response.md 的 set_content_provider 实现无限流式下载（如日志实时导出），或参考 s04-static-files.md 用 set_mount_point 挂载静态目录后配合全局头下发 Content-Disposition。仓库中的 example/upload.cc 提供了文件读写相关的完整服务端示例，可作为扩展参考。

小结

在 cpp-httplib 中实现下载响应不需要任何专属 API——Content-Disposition: attachment 头 + set_file_content（磁盘文件）或 set_content（内存数据）即可完成。底层由 httplib.h 的 mmap 文件提供者、自动 Content-Length、Range 与压缩协同共同保证大文件下载的稳定与高效。记住三个实践要点：静态文件用 set_file_content、动态导出用 set_content、非 ASCII 文件名务必同时提供 filename= 与 filename*=UTF-8''... 双轨头。