从 2014 年起，Go 的 HTTP/2 实现一直"寄养"在 golang.org/x/net/http2 里——标准库内部靠代码生成的 h2_bundle.go 引用它，对外却要求需要细粒度配置的用户自己 import 这个外部模块。2026 年 8 月，Go 1.27 发布，这场历时两年、拆分为 11 个子任务的迁移正式收官：HTTP/2 的真源（source of truth）移入 net/http/internal/http2，x/net/http2 转型为兼容外壳，其 Transport/Server 等 API 正式废弃。本文讲清楚三件事：为什么要迁、架构怎么变、你的代码要不要改。

一、为什么要把 HTTP/2 搬回标准库

先看迁移前的尴尬架构：

迁移前（Go 1.26 及以前）的 HTTP/2 依赖关系

┌──────────────────────────────────────────────┐
│  你的代码                                     │
│    │ import "net/http"        │ import x/net/http2  │
│    ▼                          ▼              │
│  net/http ──── h2_bundle.go ──┘              │
│  （代码生成工具把 x/net/http2                 │
│    打包成单文件塞进标准库，                    │
│    解决循环依赖）                             │
│                                              │
│  golang.org/x/net/http2（外部模块）           │
│    ├── 真正的实现源码在这里                    │
│    └── 需要 ConfigureTransport 等细粒度       │
│        配置的用户必须自己 import              │
└──────────────────────────────────────────────┘

这个架构带来的问题积累了很多年：

1. 安全补丁回合慢。HTTP/2 的漏洞修复发生在 x/net，然后回灌标准库，两个发布节奏、两套审批流程。Rapid Reset（CVE-2023-44487）这类攻击活跃期，响应延迟就是风险。
2. 改动无法原子化。一次涉及 HTTP/1 与 HTTP/2 联动的修改，要同时动标准库和外部模块，版本组合爆炸。
3. 配置体验割裂。调一个 HTTP/2 参数（比如连接级流控）必须 import golang.org/x/net/http2 再调 ConfigureTransport——"标准库原生支持 HTTP/2"这句话，在需要定制时就不成立了。

Go 团队把这坨历史债务拆成了 11 个可独立评审、独立回退的子任务（#67819、#77695、#78064、#78508 等），渐进式推进而不是一次性重写——大型核心组件迁移的教科书式操作。

二、Go 1.27 之后：双实现架构

迁移完成后的架构关系发生了根本反转：

迁移后（Go 1.27+）的架构

net/http/internal/http2  ←── 真源（source of truth）
  所有新特性开发都在这里，安全修复随 Go 补丁版发布

golang.org/x/net/http2   ←── 兼容外壳，双实现并存
  ├── Go < 1.27 环境：使用原始实现（老协议栈）
  ├── Go ≥ 1.27 环境：默认使用 wrapping 实现
  │     （薄壳，内部转发到 net/http）
  └── 构建标签 http2legacy：强制用回原始实现

x/net/http2 的 README 说得很直白：

As of Go 1.27, the source of truth has moved to the standard library package net/http/internal/http2. All new feature development should happen in that package. Only critical bug fixes and security fixes will be backported to x/net.

对应到 API 层面：

x/net/http2 旧 API	状态	标准库替代
http2.ConfigureTransport(t1)	deprecated	http.Transport.Protocols + http.Transport.HTTP2
http2.ConfigureServer(s, conf)	deprecated	http.Server.Protocols + http.Server.HTTP2
http2.Transport / http2.Server	deprecated	http.Transport.NewClientConn / 标准库 Server
http2.ClientConnPool	deprecated	标准库连接池接管
http2.Framer 等底层帧 API	保留	高级用户按需使用（非废弃）

三、迁移实战：六段可运行代码

大部分项目什么都不用改。以下六段代码覆盖了需要动手的场景。

3.1 场景一：客户端默认开启 HTTP/2（大多数人的现状）

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	// Go 1.6+ 起 http.DefaultTransport 就默认启用 HTTP/2（TLS 场景）
	// 迁移到标准库后行为不变，但实现路径变了：
	//   Go ≤ 1.26: net/http → h2_bundle.go（x/net 快照）
	//   Go ≥ 1.27: net/http → internal/http2（真源）
	resp, err := http.Get("https://friday-go.icu/")
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	// resp.Proto 会显示 "HTTP/2.0"（对 HTTPS 站点）
	fmt.Println("Proto:", resp.Proto)
	body, _ := io.ReadAll(io.LimitReader(resp.Body, 1<<10))
	fmt.Printf("首 1KB: %.100s...\n", body)
}

3.2 场景二：从 ConfigureTransport 迁移到标准库 API

package main

import (
	"log"
	"net/http"
)

func oldWay() {
	// ❌ 旧写法（Go 1.27 起废弃，未来版本将删除）
	//
	// import "golang.org/x/net/http2"
	// transport := &http.Transport{}
	// http2.ConfigureTransport(transport)
	// client := &http.Client{Transport: transport}
	_ = "deprecated"
}

func newWay() {
	// ✅ 新写法：显式声明协议栈
	transport := &http.Transport{
		// Protocols 字段（Go 1.24+）：声明客户端使用的协议
		// UnencryptedHTTP2 = h2c（明文 HTTP/2，用于内网/代理场景）
		// HTTP2 默认已包含在默认值中
		ForceAttemptHTTP2: true,
	}
	client := &http.Client{Transport: transport}

	// HTTP/2 细粒度参数：不再需要 import 外部包
	_ = transport.HTTP2 // *http.HTTP2Config，见 3.3 的完整示例
	_ = client
	log.Println("client ready")
}

func main() {
	newWay()
}

3.3 场景三：HTTP/2 参数调优（以前必须 import x/net 的场景）

package main

import (
	"log"
	"net/http"
	"time"
)

func main() {
	// Go 1.27+：HTTP/2 参数直接挂在 Transport/Server 上
	transport := &http.Transport{
		ForceAttemptHTTP2: true,
		HTTP2: &http.HTTP2Config{
			// 连接级流控窗口
			MaxHeaderListSize: 1 << 20, // 1 MiB 头部大小上限
			// Ping 间隔：检测死连接
			PingTimeout: 15 * time.Second,
			// 每连接并发流数调优（对高并发网关很重要）
			// 具体字段以 go doc net/http.HTTP2Config 为准
		},
	}
	server := &http.Server{
		Addr: ":8443",
		// 服务端同理：Protocols + HTTP2 字段
		HTTP2: &http.HTTP2Config{
			MaxHeaderListSize: 1 << 20,
		},
	}
	_ = transport
	log.Fatal(server.ListenAndServeTLS("cert.pem", "key.pem"))
}

字段名以 go doc net/http.HTTP2Config 输出为准——标准库正在持续补充此结构体的字段，这正是"新特性开发发生在标准库"的直接体现。

3.4 场景四：启用 h2c（明文 HTTP/2）

以前启用 h2c 需要 h2c.NewHandler 包装，现在标准库原生支持：

package main

import (
	"fmt"
	"net/http"
)

func main() {
	mux := http.NewServeMux()
	mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
		fmt.Fprintf(w, "Proto: %s\n", r.Proto)
	})

	server := &http.Server{
		Addr:    ":8080",
		Handler: mux,
		// 关键：显式包含 UnencryptedHTTP2，即 h2c
		Protocols: []string{"http/1.1", "h2c"},
	}
	server.ListenAndServe()
}

# 验证（curl 需 7.48+）
curl --http2-prior-knowledge http://localhost:8080/
# 输出: Proto: HTTP/2.0

3.5 场景五：被迫继续用老实现（过渡期逃生舱）

如果 wrapping 实现暴露了行为差异，短期可以用构建标签回退：

# http2legacy：让 x/net/http2 在 Go 1.27+ 上继续使用原始实现
go build -tags http2legacy ./...

这是逃生舱，不是长期方案。官方会在未来版本移除原始实现，把它写进迁移计划等于埋雷。

3.6 场景六：直接操作 HTTP/2 连接（高级）

package main

import (
	"fmt"
	"net/http"
)

func main() {
	transport := &http.Transport{ForceAttemptHTTP2: true}
	_ = transport

	// Go 1.27+: Transport.NewClientConn 可以显式建立 HTTP/1 或 HTTP/2 连接
	// 替代原来的 http2.Transport + http2.ClientConn 组合
	// 典型用途：连接复用监控、自定义连接调度
	_ = fmt.Sprintf("see go doc net/http.Transport.NewClientConn")
}

四、行为变化清单：升级后值得盯的点

升级到 Go 1.27 后，除了实现搬家，还有几个行为层面的变化：

1. RFC 9218 客户端优先级。Go 1.27 服务端遵循新的 HTTP 优先级信号（取代老的依赖树式优先级）。如果中间件解析过旧优先级帧，需要适配。
2. Response.Body 关闭时自动 drain。关闭 body 会自动读完剩余数据以利连接复用——对大响应，旧代码里"不读完就 Close"的连接行为会变化。
3. x/net/http2 的 Transport.RoundTrip 错误语义。wrapping 实现下错误类型可能与原始实现有细微差异，依赖 http2.ConnectionError 等类型做重试判断的代码，建议在 1.27 上跑一遍故障注入测试。
4. 安全修复节奏变快。今后 HTTP/2 的 CVE 修复随 Go 月度补丁版发布——升级 Go 版本要进你的安全运维例行项。

五、迁移检查清单

□ CI 全面升级到 Go 1.27+，全量构建 + 测试通过
□ grep 项目中所有 "golang.org/x/net/http2" import
  ├── 只用了 h2c.NewHandler / ConfigureTransport？
  │     → 迁移到标准库 Protocols/HTTP2 字段（见 3.2/3.4）
  └── 用了 Framer 等底层帧 API？
        → 暂时保留，关注 x/net 后续弃用公告
□ 依赖第三方库（gRPC、反代、网关）中转依赖 x/net/http2 的
  → 升级到已适配 Go 1.27 的版本，跑回归
□ 压测对比升级前后 P99 延迟（实现搬家理论上零行为差异，
  但 wrapping 层值得用数据说话）
□ 不要使用 -tags http2legacy 除非有明确的行为回归需要兜底
□ 把 "Go 版本升级" 纳入安全补丁例行项（HTTP/2 修复随之发布）

六、这次迁移的工程启示

站在架构演进的角度，这次迁移有三个值得复用的经验：

1. 渐进式优于重写。11 个子任务、每个独立可回退，两年走完。对比某些"一次性 rewrite"的失败案例，前者把风险摊平到了每个迭代里。
2. 兼容外壳是退出通道。x/net/http2 没有立刻消失，而是变成"版本探测 + 转发"的外壳，让存量用户有过渡期。废弃 API 不等于删除 API。
3. 安全驱动的架构债优先级。让迁移真正启动的推力是补丁回合慢——当架构债开始影响安全响应速度，它就从"可以拖"变成了"必须还"。

七、参考资料

1. Tony Bai：两年攻坚、11 个子任务闭环，Go 终于把 HTTP/2 接回标准库（2026-09-08）
2. pkg.go.dev: golang.org/x/net/http2 — README 与双实现说明
3. Go 1.27 Release Notes
4. golang/go#67819: net/http: move HTTP/2 implementation into the standard library
5. 本站相关文章：Go 1.27 encoding/json/v2 迁移实战、Go 1.27 泛型方法生产实践、Go 1.25 Green Tea GC 深度测评