8.1 讲了四个核心变化，这一节是逐项的弃用对照表。源文档给出的弃用项很多，按「请求体 / Cookie 与 Headers / 工具函数 / Node 与 Web 适配 / 类型导出」五组归并。每组都是三列：v1 写法 → v2 写法 → 备注。

💡 一个好消息先说在前面：v2 仍然导出所有被弃用的 v1 名称，所以存量代码不会一升级就编译报错——这些名字只是打上了弃用标记，会逐步移除。真正的破坏性来自 8.1 讲的「模型级变化」（send→return、router 合并），而不是这张表。

四个废弃的 H3Event 属性

先列最隐蔽的一类：下面四个属性在 v2 被标记为废弃（未来版本可能移除）。它们现在还能用，但应尽早换成新的取值路径，因为拿到的对象形态已经变了：

v1 属性	v2 取值	备注
event.path	event.url.pathname + event.url.search	不再单独返回路径，需自己拼 query
event.method	event.req.method	改从标准 Request 读
event.headers	event.req.headers	现在是标准 Headers
event.node	event.runtime.node	仅 Node 运行时存在，挪了位置

最容易踩的坑是 event.path：v1 只返回路径本身，v2 建议用 event.url.pathname（注意不含 query string）。如果你代码里既用 event.path 又自己另取 query，迁移后直接换成 event.url 上的两个字段，语义更清晰。

一、请求体工具

v2 的原则是「请求体优先用原生 event.req.*」，旧的 read* 包装大多有了标准替代；同时 readBody 不再用 destr 自动反序列化（见 6.2/7.7，这关乎原型污染，必须自己过滤）。

v1 写法	v2 写法	备注
readRawBody(event)	event.req.text() / event.req.arrayBuffer()	直接读原始文本或二进制
getBodyStream(event)	event.req.body	原生 ReadableStream
getRequestWebStream(event)	event.req.body	同上
readFormData(event)	event.req.formData()	标准 FormData
readMultipartFormData(event)	event.req.formData()	同上，含文件
readFormDataBody(event)	event.req.formData()	同上

二、Cookie 与 Headers

v2 全面改用标准 Web Headers：Header 值现在永远是普通 string，不再可能是 null / undefined / number / string[]——这是类型上的破坏性变化，v1 里判断「header 是否存在」时写 if (header) 还能兼容 falsy，v2 里要改成 if (header !== null) 或直接用 headers.has(name)。

Set-Cookie 因为标准 Headers 只留一个字符串，改用 headers.getSetCookie()，它始终返回字符串数组（每个 cookie 一项），多 cookie 场景下比 v1 的拼接字符串好处理得多。

// v1：Set-Cookie 是拼接字符串，要自己拆分
const cookies = getResponseHeader(event, "set-cookie")?.split(", ");

// v2：getSetCookie 直接给数组
const cookies = event.res.headers.getSetCookie();

⚠️ getRequestProtocol（以及 getRequestURL）不再默认信任 x-forwarded-proto 头。 这是安全相关的关键变化：v2 必须显式 opt in 才信任它——getRequestProtocol(event, { xForwardedProto: true })。这与 getRequestHost（xForwardedHost）和 getRequestIP（xForwardedFor）既有的 opt-in 行为一致。只在你确定前面有可信的反向代理或 CDN 时再开，否则客户端可以伪造协议头、绕过你的 HTTPS 强制逻辑。

三、工具函数

这一组最大，再按用途拆成六个子表。

应用与路由工具

v1 写法	v2 写法	备注
createApp / createRouter	new H3()	两者合并，见 8.1

错误工具

v1 写法	v2 写法	备注
createError / H3Error	HTTPError	统一错误类型
isError(error)	HTTPError.isError(error)	改为类型上的静态方法

Handler 工具

v1 写法	v2 写法	备注
eventHandler / defineEventHandler	defineHandler（或直接用函数）	命名更短，函数本身即可作 handler
lazyEventHandler	defineLazyEventHandler	仅改名字
isEventHandler	（已移除）	任意函数都可以是 handler，不再需要判断
useBase	withBase	前缀应用工具改名
defineRequestMiddleware / defineResponseMiddleware	（已移除）	v2 用 (event, next) 中间件或全局钩子替代

请求工具

v1 写法	v2 写法	备注
getHeader(event, name) / getRequestHeader(event, name)	event.req.headers.get(name)	直接读标准 Headers
getHeaders(event) / getRequestHeaders(event)	Object.fromEntries(event.req.headers.entries())	全量转对象
getRequestPath(event)	event.url.pathname	改用 URL.pathname
getMethod(event)	event.req.method	改用标准 Request
getRequestProtocol(event)	event.req 取协议 + { xForwardedProto: true } 才信转发头	见本节上方警告

响应工具

v1 写法	v2 写法	备注
getResponseHeader / getResponseHeaders	event.res.headers.get(name)	直接读标准 Headers
setHeader / setResponseHeader / setHeaders / setResponseHeaders	event.res.headers.set(name, value)	统一到 set
appendHeader / appendResponseHeader / appendResponseHeaders	event.res.headers.append(name, value)	统一到 append
removeResponseHeader / clearResponseHeaders	event.res.headers.delete(name)	统一到 delete
appendHeaders	appendResponseHeaders	别名收敛
defaultContentType	event.res.headers.set("content-type", type)	不再有专门函数
getResponseStatus / getResponseStatusText / setResponseStatus	event.res.status / event.res.statusText	改用标准 Response 字段

其他工具

v1 写法	v2 写法	备注
createEventStream(event)	new EventStream(event)	用 class 构造，见 5.2
isStream(value)	value instanceof ReadableStream	不再有判断函数
isWebResponse(value)	value instanceof Response	同上
splitCookiesString	用 cookie-es 的 splitSetCookieString	移出核心，转第三方
MIMES	（已移除）	不再内置 MIME 映射

四、Node 与 Web 适配

v2 把适配函数统一成「Handler / Request / Response」命名，并移除了一批一次性转换工具（因为它们已被 Web API 原生取代）。

v1 写法	v2 写法	备注
defineNodeListener	defineNodeHandler	仅改名字
fromNodeMiddleware	fromNodeHandler	仅改名字
toNodeListener	toNodeHandler	仅改名字
createEvent(event)	（已移除）	改用 Node 适配器 toNodeHandler(app)
fromNodeRequest	（已移除）	同上
promisifyNodeListener	（已移除）	——
callNodeListener	（已移除）	——
fromPlainHandler	（已移除）	直接改用 Web API
toPlainHandler	（已移除）	直接改用 Web API
fromPlainRequest	（已移除）	改用 Web API 或 mockEvent 测试
callWithPlainRequest	（已移除）	直接改用 Web API
fromWebRequest	（已移除）	直接改用 Web API
callWithWebRequest	（已移除）	——

这一组移除项很多，但逻辑很一致：v2 本身就是 Web 标准的，那些"把 H3 事件 ↔ 平台原语"反复转来转去的桥接函数不再需要——你直接操作 Request / Response 即可。唯一保留的适配层是 Node 的 toNodeHandler，因为 Node 生态仍需一个入口。

五、类型导出

类型名几乎全改了，目标是对齐 Web 标准命名。下面是改名映射：

v1 类型	v2 类型	备注
App	H3	对齐新实例名
AppOptions	H3Config	——
_RequestMiddleware	RequestMiddleware	去掉下划线前缀
_ResponseMiddleware	ResponseMiddleware	同上
NodeListener	NodeHandler	命名对齐
TypedHeaders	RequestHeaders / ResponseHeaders	按请求/响应拆开
HTTPHeaderName	RequestHeaderName / ResponseHeaderName	同上
H3Headers	原生 Headers	不再有包装类型
H3Response	原生 Response	同上
MultiPartData	原生 FormData	同上
RouteNode	RouterEntry	路由条目
CreateRouterOptions	RouterOptions	——

已删除（不再导出的）类型：WebEventContext、NodeEventContext、NodePromisifiedHandler、AppUse、Stack、InputLayer、InputStack、Layer、Matcher、PlainHandler、PlainRequest、PlainResponse、WebHandler。

如果你的代码里 import type 了这些名字，升级后 Typescript 会报「找不到名称」——对照上表改名字（或删掉已删除的）即可。

把这五组对照表与 8.1 的四点核心变化合起来，就是 v1→v2 的完整迁移面。下一节（8.3）回到 v2 正式版的官方发布说明，从「为什么值得升级」的角度再梳理一遍。