本文介绍如何使用 `io.copy` 将上游 http 响应直接流式写入 `http.responsewriter`，避免将整个响应体加载到内存，适用于大文件代理、图片/视频中转等场景。
在 Go Web 开发中，常需将外部 API 返回的文件（如图片、PDF、视频）透明地转发给客户端，同时保证低内存占用和高吞吐。关键诉求是：不缓存完整响应体，而是边读边写，实现恒定内存消耗（O(1)）的流式传输。
此时，io.Copy 是最直接、最安全、最符合 Go 惯用法的解决方案。它内部采用固定大小缓冲区（默认 32KB），持续从 io.Reader（如 resp.Body）读取数据，并写入 io.Writer（如 http.ResponseWriter），全程无需分配额外大内存。
以下是一个生产就绪的示例：
Unified LLM Gateway - One API for 70+ AI models. Route to GPT, Claude, Gemini, Qwen, Deepseek, Grok and more
下载
统一LLM网关 - 一个API对接70+AI模型，使用单一API密钥即可调用GPT、Claude、Gemini、Qwen、Deepseek、Grok等主流模型。
func pipeResponse(w http.ResponseWriter, r *http.Request) {
// 1. 发起上游请求（建议使用带超时的 client）
client := &http.Client{
Timeout: 30 * time.Second,
}
resp, err := client.Get("https://example.com/large-file.zip")
if err != nil {
http.Error(w, "Failed to fetch resource: "+err.Error(), http.StatusBadGateway)
return
}
defer resp.Body.Close() // 确保上游连接及时释放
// 2. 复制关键响应头（避免泄露敏感头，仅透传安全/必要字段）
for name, values := range resp.Header {
// 过滤掉 hop-by-hop 头（如 Connection, Transfer-Encoding, Upgrade 等）
if !shouldPassThroughHeader(name) {
continue
}
for _, value := range values {
w.Header().Add(name, value)
}
}
// 3. 流式拷贝主体（核心步骤）
// io.Copy 自动处理读写循环、错误传播与缓冲
_, err = io.Copy(w, resp.Body)
if err != nil {
// 注意：此处 err 可能是客户端提前断连（如用户关闭页面），通常可忽略或记录为 warn
log.Printf("Copy to client failed: %v", err)
// 不再调用 http.Error —— 连接已中断，写入会失败
}
}
// shouldPassThroughHeader 过滤禁止透传的 hop-by-hop 头
func shouldPassThroughHeader(key string) bool {
switch strings.ToLower(key) {
case "connection", "keep-alive", "proxy-authenticate",
"proxy-authorization", "te", "trailers", "transfer-encoding", "upgrade":
return false
}
return true
}✅ 为什么不是 io.Pipe？
io.Pipe() 用于构造一对关联的 io.Reader 和 io.Writer，适用于需要在 goroutine 间异步桥接读写流的场景（如并发生成并消费数据）。而本例中，resp.Body（已存在 Reader）和 w（已存在 Writer）都是现成的，无需中间管道 —— 强行使用 io.Pipe 反而引入不必要的 goroutine 和同步开销，增加复杂度与出错风险。
⚠️ 重要注意事项：
- 勿手动设置 Content-Length：io.Copy 无法预知总长度，且上游可能使用 chunked 编码。若强行设置错误的 Content-Length，会导致客户端解析失败。应让 Go 的 net/http 自动处理编码（如自动添加 Transfer-Encoding: chunked 当长度未知时）。
- 务必 defer resp.Body.Close()：防止连接泄漏，即使 io.Copy 出错也必须关闭。
- 超时控制必不可少：上游响应慢或挂起时，需通过 http.Client.Timeout 或 context.WithTimeout 主动中断，避免阻塞服务端 goroutine。
- 头信息需过滤：直接 w.Header().Set(...) 所有上游头是危险的；必须剔除 hop-by-hop 头，否则违反 HTTP 协议，可能导致代理故障或安全问题。
总结：io.Copy(dst, src) 是 Go 中流式代理的黄金标准 —— 简洁、高效、健壮。它让开发者专注业务逻辑，而将底层流控、缓冲、错误恢复交由标准库可靠实现。
