深入 Electron ProtocolResponse：自定义协议响应对象全字段详解与网络栈实现剖析

ProtocolResponse 是 Electron protocol 模块中用于描述"一次协议响应"的核心数据结构：当你在主进程注册自定义协议（如 registerBufferProtocol、registerStreamProtocol、registerFileProtocol、registerHttpProtocol 及对应的 intercept* 系列方法）后，处理函数通过 callback 返回的对象就是这个 ProtocolResponse。读懂它的每一个字段——从 HTTP 状态码、MIME 类型、响应头到文件路径、上游 URL、上传数据——是正确实现自定义协议、代理请求与本地文件服务的关键。本文以官方结构定义 protocol-response.md 为骨架，结合 Electron 网络栈源码 electron_url_loader_factory.cc 逐字段剖析其解析规则与底层行为，并给出可直接运行的完整示例。

ProtocolResponse 的适用场景：谁在消费这个对象

从源码结构看，ProtocolResponse 是回调式（callback-style）协议 API 的响应载体。在 protocol.md 中，registerFileProtocol、registerBufferProtocol、registerStringProtocol、registerHttpProtocol、registerStreamProtocol 以及全部 intercept* 方法的 handler 签名均为 (request, callback) => ...，其中 callback 接受的值就是 string | ProtocolResponse（或 Buffer | ProtocolResponse、ReadableStream | ProtocolResponse）这类联合类型，而传入的 request 则为 ProtocolRequest。

需要注意版本前提：这些 register*/intercept* 方法在当前仓库的文档中已标记为 Deprecated——它们已被统一替换为基于标准 Request/Response 对象的 protocol.handle(scheme, handler)。ProtocolResponse 仍用于理解旧 API 的行为，以及阅读大量存量项目代码；而新代码应当优先使用 protocol.handle。因此，理解 ProtocolResponse 既是为了兼容旧代码，也是为了理解 Electron 网络栈如何把"一个 JS 对象"翻译成 Chromium 的 URLResponseHead 与数据管道。

全字段参考：类型、默认值与生效条件

以下是 docs/api/structures/protocol-response.md 定义的全部字段，并结合源码补充了实现层面的细节：

字段	类型	默认值	生效场景
error	Integer (optional)	无	所有协议。赋值后请求以该 net 错误码失败（参见 Chromium net error list）
statusCode	number (optional)	200	所有协议
charset	string (optional)	"utf-8"	所有协议
mimeType	string (optional)	"text/html"	所有协议；若 headers 中已设置 content-type 则被忽略
headers	Record<string, string | string[]> (optional)	无	所有协议；键必须为字符串，值为字符串或字符串数组
data	Buffer | string | ReadableStream (optional)	无	响应体；Buffer / string / 可读流三选一，其他类型的响应中会被忽略
path	string (optional)	无	仅文件响应
url	string (optional)	无	仅 URL 响应
referrer	string (optional)	无	仅文件与 URL 响应
method	string (optional)	无	仅文件与 URL 响应
session	Session (optional)	当前 session	仅 URL 响应，指定用于发起请求的会话
uploadData	ProtocolResponseUploadData (optional)	无	仅 URL 响应且 method 为 "POST"

error：把响应变成一次网络错误

error 是唯一一个"不产生响应体"的字段：一旦赋值，整次请求直接以该 Chromium net 错误码失败，例如 -1009（ERR_FILE_NOT_FOUND）会让渲染进程像文件缺失一样处理该请求，而不是收到一个 HTTP 错误页面。

源码印证位于 StartLoading：解析响应对象时首先检查 error 键，命中即调用

if (dict.Get("error", &error_code)) {
  OnComplete(std::move(client), request_id,
             network::URLLoaderCompletionStatus(error_code));
  return;
}

即直接把 error_code 塞进 network::URLLoaderCompletionStatus 结束加载，后续所有 statusCode/data 等字段全部被跳过。可用的错误码列表以 Chromium 的 net/base/net_error_list.h 为准（官方文档通过链接指向该文件）。

statusCode、charset 与 mimeType：响应头的构建逻辑

这三个字段共同决定响应行与 MIME 元数据，解析全部集中在 ToResponseHead 函数中：

head->mime_type = "text/html";   // mimeType 默认值
head->charset = "utf-8";        // charset 默认值
...
const int status_code =
    dict.ValueOrDefault("statusCode", static_cast<int>(net::HTTP_OK));  // 默认 200
head->headers = base::MakeRefCounted<net::HttpResponseHeaders>(
    absl::StrFormat("HTTP/1.1 %d %s", status_code,
                    net::GetHttpReasonPhrase(...)));

文档中三个默认值（200 / utf-8 / text/html）由此得到源码级确认。此外还有两条容易被忽略的规则：

1. mimeType 与 content-type 的优先级。源码先记录 has_mime_type（来自 dict.Get("mimeType", ...)），再遍历 headers：若发现 content-type 键，则直接从该头反解 MIME 与 charset 并置 has_content_type = true（L171-L175）；最后才执行"仅当设置了 mimeType 且没有 content-type 时，才把 MIME 类型写成 content-type 头"（L183-L186）。这正是文档所说"如果 headers 中已设置 content-type，mimeType 会被忽略"的实现。
2. content-length 会被单独解析：headers 中的字符串型 content-length 会被解析进 head->content_length（L176-L179），供网络栈判断响应体长度。

headers：键值校验与多值头

headers 是一个 Record<string, string | string[]>。实现上对每个条目做严格校验（L151-L180）：

• 键必须通过 net::HttpUtil::IsValidHeaderName 校验，非法头名被静默跳过；
• 字符串值必须通过 net::HttpUtil::IsValidHeaderValue 校验，否则该条目被丢弃；
• 数组值则逐项追加，天然支持 set-cookie、www-authenticate 等需要多值头的场景；
• 非字符串、非数组的值直接忽略。

这种"静默丢弃"意味着拼错的头不会抛错，只会悄悄消失——排查自定义协议头丢失问题时，应首先核对头名与头值是否含非法字符。

data：Buffer、string 与可读流的类型推断

data 是响应体。在新版代码路径（kFree 分支）中，Electron 按以下顺序推断类型：

// |data| can be either a string, a buffer or a stream
if (data->IsArrayBufferView()) {
  StartLoadingBuffer(...);          // Buffer / 二进制
} else if (data->IsString()) {
  SendContents(...);               // string
} else if (LooksLikeStream(...)) {
  StartLoadingStream(...);         // Node 可读流
} else {
  // 回退：从 dict 中找 url / path
}

• Buffer 走 StartLoadingBuffer（L766-L773），直接取底层字节写入数据管道；
• string 走 SendContents，按 charset 语义作为文本内容下发；
• 可读流走 StartLoadingStream，任何实现了 readable stream API（发出 data/end/error 事件）的对象都可以，例如 fs.createReadStream('index.html')；
• 若 data 为 null 且对象中带有 url 或 path，则回退到 URL 响应或文件响应——这正是"data 在其他类型响应中会被忽略"这一文档描述的底层原因。

对于旧版 registerBufferProtocol / registerStringProtocol / registerStreamProtocol，源码中保留了 kBuffer/kString/kStream 等分支，只接受对应类型的 data，类型不符则返回 ERR_FAILED（L662-L711）。

path：文件响应

path 指定作为响应体的文件，仅对文件响应有效，且必须是绝对路径。实现位于 StartLoadingFile：

request.url = net::FilePathToFileURL(path);
if (!opts.IsEmpty()) {
  opts.Get("referrer", &request.referrer);   // referrer 只在此生效
  opts.Get("method", &request.method);        // method 只在此生效
}
...
asar::CreateAsarURLLoader(request, std::move(loader), std::move(client), head->headers);

两点值得注意：一是 referrer 与 method 字段确实在此被读取并注入底层 ResourceRequest，与文档"仅用于 file 和 URL 响应"的说明完全一致；二是文件加载统一走 asar 感知的 CreateAsarURLLoader，意味着返回 .asar 包内文件同样受支持，并且会默认附加 Access-Control-Allow-Origin: * 头以便绕过 CORS。

url、session、method、referrer 与 uploadData：URL 响应（代理请求）

url 表示"下载该 URL 并把结果作为响应体管道给调用方"，仅对 URL 响应有效，典型用途是用自定义 scheme 代理真实 HTTP 请求。实现位于 StartLoadingHttp，其中每个字段的处理一目了然：

dict.Get("url", &request->url);
dict.Get("referrer", &request->referrer);
if (!dict.Get("method", &request->method))
  request->method = original_request.method;   // 未指定时沿用原始请求方法

// uploadData 仅在非 GET/HEAD 方法下才会被读取
base::DictValue upload_data;
if (request->method != net::HttpRequestHeaders::kGetMethod &&
    request->method != net::HttpRequestHeaders::kHeadMethod)
  dict.Get("uploadData", &upload_data);

// session 未指定时，回退到该协议注册所在的 session
api::Session* session = nullptr;
ElectronBrowserContext* browser_context =
    dict.Get("session", &session) && session ? session->browser_context()
                                             : serving_browser_context.get();

new URLPipeLoader(browser_context->GetURLLoaderFactory(), std::move(request),
                  std::move(loader), std::move(client), ..., std::move(upload_data));

• session 默认值：文档说"默认复用当前 session"，源码中"当前 session"具体指该协议处理器所注册到的 ElectronBrowserContext（即注册 handler 的那个 session），而非全局默认 session——这对多 partition 场景尤其关键；
• uploadData 的结构定义在 protocol-response-upload-data.md：contentType（string，内容的 MIME 类型）与 data（string | Buffer，要发送的内容）。实现侧仅在 method 非 GET/HEAD 时才从响应对象中读取 uploadData（L827-L830），随后在 URLPipeLoader 构造时取出 contentType 与 data 组装请求体（L223-L255）。

另外，URL 响应通过 URLPipeLoader（L215）把上游响应流式转发给网络栈，源码注释明确指出：与直接新建 loader 不同，协议处理器经由该转发路径可以绕过 CORS 限制——这是自定义协议能"内联"跨域内容的底层机制。

附带能力：通过响应头实现重定向

虽然不属于 ProtocolResponse 的文档字段，但 StartLoading 中有一段值得了解的行为：若你在 headers 中返回 Location 头并配合 3xx 状态码（head->headers->IsRedirect(&location) 命中），Electron 会显式构造 net::RedirectInfo 并调用 OnReceiveRedirect，由网络栈按标准重定向语义处理，MAIN_FRAME 请求还会按策略更新第一方 URL。换言之，statusCode: 302 + headers: { location: ... } 是一个可用的重定向手段。

实战示例：覆盖四类响应类型

以下示例对应 protocol.md 中已弃用但仍有大量存量使用的回调式 API，完整展示 ProtocolResponse 各字段组合方式：

1. Buffer 响应（mimeType + data）

protocol.registerBufferProtocol('atom', (request, callback) => {
  callback({ mimeType: 'text/html', data: Buffer.from('<h5>Response</h5>') })
})

等价于 statusCode 取默认 200、charset 取默认 utf-8、mimeType: 'text/html' 隐式生成 content-type 头。

2. 流式响应（headers + data 为可读流）

const { PassThrough } = require('node:stream')

function createStream (text) {
  const rv = new PassThrough() // PassThrough 也是 Readable 流
  rv.push(text)
  rv.push(null)
  return rv
}

protocol.registerStreamProtocol('atom', (request, callback) => {
  callback({
    statusCode: 200,
    headers: { 'content-type': 'text/html' },
    data: createStream('<h5>Response</h5>')
  })
})

注意此处 content-type 通过 headers 显式设置，因此即使再传 mimeType 也会被忽略（参见上文优先级规则）。也可以直接传文件流：

protocol.registerStreamProtocol('atom', (request, callback) => {
  callback(fs.createReadStream('index.html'))
})

3. 文件响应（path + referrer）

protocol.registerFileProtocol('app', (request, callback) => {
  const filePath = path.join(__dirname, request.url.slice('app://'.length))
  callback({ path: filePath })  // 必须为绝对路径；也可简写 callback(filePath)
})

4. URL 响应/代理（url + method + session + uploadData）

protocol.registerHttpProtocol('proxy', (request, callback) => {
  callback({
    url: 'https://api.example.com/data',
    method: 'POST',
    session: session.fromPartition('persist:example'), // 可选，默认复用注册所在 session
    uploadData: { contentType: 'application/json', data: Buffer.from(JSON.stringify({ id: 1 })) },
    headers: { 'content-type': 'application/json' }
  })
})

5. 以网络错误失败

protocol.registerFileProtocol('secure', (request, callback) => {
  if (!allowAccess(request.url)) {
    callback({ error: -3 }) // net::ERR_ACCESS_DENIED，请求直接失败
    return
  }
  callback({ path: resolveSecureFile(request.url) })
})

现代写法对照：同等能力在 protocol.handle 下使用标准 Response 表达，例如 protocol.md 中的示例用 new Response('<h1>hello, world</h1>', { headers: { 'content-type': 'text/html' } }) 或 net.fetch(...) 返回上游响应，配合 registerSchemesAsPrivileged 声明 scheme 的 standard/secure/supportFetchAPI 等特权。新项目应直接采用该模式；ProtocolResponse 的字段语义则用于阅读与迁移旧代码。协议本身的注册/查询入口实现位于 protocol.ts，端到端行为可参考 api-protocol-spec.ts。

常见问题与易错点

• 返回了非法字段组合：kFree 分支下若对象既没有可识别的 data（Buffer/string/流），又没有 url/path，源码会以 ERR_FAILED 结束请求（L752-L755），渲染侧表现为请求失败，而主进程无任何异常——排查时应先检查 ProtocolResponse 字段是否成组出现。
• 旧 API 的类型强约束：registerBufferProtocol 返回 string、registerStringProtocol 返回 Buffer 都会得到 ERR_FAILED，因为每个分支只接受单一类型（L662-L684）。
• uploadData 在 GET 下无效：源码明确只在非 GET/HEAD 时读取 uploadData，POST 场景才应提供。
• error 优先于一切：error 在响应对象解析的最前部被检查，命中后其余字段全部失效，适合做访问控制失败的统一出口。
• 头静默丢弃：非法头名/头值不会报错，排查"自定义头没生效"时优先检查拼写与字符合法性。

小结

ProtocolResponse 用一个扁平对象统一表达了 Electron 自定义协议的五类响应形态：错误（error）、内联内容（data）、本地文件（path）、远程代理（url + session + uploadData），以及贯穿其中的响应元数据（statusCode/charset/mimeType/headers）。源码层面，ToResponseHead 与 StartLoading 完成了从 JS 对象到 Chromium URLResponseHead、数据管道与 URLPipeLoader 的完整翻译，字段默认值、优先级与生效条件均与官方文档一一对应。对于新代码，建议迁移到 protocol.handle 与标准 Request/Response；对于存量代码，本文的字段级行为说明可作为定位"响应不符合预期"问题的直接依据。