最小通用 Web 平台 API

草案,

本版本:
https://min-common-api.proposal.wintertc.org/
问题跟踪:
GitHub
编辑者:
(Cloudflare)

摘要

面向非浏览器 ECMAScript 运行时的最小通用 Web 平台 API。

介绍

除了网页浏览器外,目前有大量 JavaScript 运行时环境被广泛用于 Web 服务器和边缘平台。其中一个重要原因是 JavaScript 能同时用于服务器端和客户端,这减少了开发者在同一代码库的不同部分工作时的专业化需求,并允许在服务器端与客户端之间复用代码。

但由于绝大多数 JavaScript 代码都运行在 Web 浏览器中,因此如果这些运行时能支持与 Web 浏览器相同的 API,就能进一步推动发展。毫不意外,越来越多的运行时环境开始支持 Web 平台 API。然而,随着此类环境数量的增加,以及选择支持的 Web 平台 API 各不相同,导致这些环境之间的互操作性较差。

因此,本 Ecma 标准定义了“最小通用 Web API”规范,列出了服务端和边缘运行时为实现 Web 互操作性所需实现的 Web 平台 API 精选最小子集。这是该标准的第一版,对应 2025 快照,每年都会发布新的快照。

1. 范围

本标准定义了 2025 快照的“最小通用 Web 平台 API”,这是由 W3C 和 WHATWG 等 Web 平台标准定义的 API 精选子集,旨在明确浏览器和非浏览器 JavaScript 运行时环境共同具备的最低能力集。

2. 一致性

符合“最小通用 Web 平台 API”的实现应当符合 ECMA-262,并且还应按本规范所列,提供相关接口与属性,并遵循对应 W3C 或 WHATWG 标准中的定义。

符合规范的运行时可以在任何 Web 平台 API 上实现特定于运行时的扩展。这些扩展应当定义为既不与任何 Web 平台 API 的规范性功能相冲突,也不导致其不符合规范。在使用此类扩展时需谨慎,因为这会降低代码在不同运行时之间的互操作性和可移植性。

本规范不禁止实现除本规范所列之外的其他 Web 平台 API。

注意:例如,Performance API 可以扩展为包含 [HR-TIME] 规范之外的其他方法或属性,比如 [PERFORMANCE-TIMELINE][USER-TIMING] 规范中定义的内容。

3. 规范性引用

下列文档被本规范引用,其中部分或全部内容构成本规范的要求。对于有日期的引用,仅适用于所引用的版本;对于无日期的引用,则适用于被引用文档的最新版本(包括任何修订)。

参考资料

规范性参考

[COMPRESSION]
Adam Rice. Compression 标准. 现行标准. URL: https://compression.spec.whatwg.org/
[CONSOLE]
Dominic Farolino; Robert Kowalski; Terin Stock. Console 标准. 现行标准. URL: https://console.spec.whatwg.org/
[DOM]
Anne van Kesteren. DOM 标准. 现行标准. URL: https://dom.spec.whatwg.org/
[ECMASCRIPT]
ECMAScript 语言规范. URL: https://tc39.es/ecma262/multipage/
[ENCODING]
Anne van Kesteren. Encoding 标准. 现行标准. URL: https://encoding.spec.whatwg.org/
[FETCH]
Anne van Kesteren. Fetch 标准. 现行标准. URL: https://fetch.spec.whatwg.org/
[FILEAPI]
Marijn Kruisselbrink. File API. URL: https://w3c.github.io/FileAPI/
[HR-TIME]
Yoav Weiss. 高精度时间. URL: https://w3c.github.io/hr-time/
[HTML]
Anne van Kesteren; 等. HTML 标准. 现行标准. URL: https://html.spec.whatwg.org/multipage/
[RFC7231]
R. Fielding, Ed.; M. Nottingham, Ed.; J. Reschke, Ed.. HTTP 语义. 2022年6月. Internet 标准. URL: https://httpwg.org/specs/rfc9110.html
[STREAMS]
Adam Rice; 等. Streams 标准. 现行标准. URL: https://streams.spec.whatwg.org/
[URL]
Anne van Kesteren. URL 标准. 现行标准. URL: https://url.spec.whatwg.org/
[URLPATTERN]
Ben Kelly; Jeremy Roman; 宍戸俊哉 (Shunya Shishido). URL Pattern 标准. 现行标准. URL: https://urlpattern.spec.whatwg.org/
[WASM-JS-API-2]
. Ms2ger. WebAssembly JavaScript 接口. URL: https://webassembly.github.io/spec/js-api/
[WASM-WEB-API-2]
. Ms2ger. WebAssembly Web API. URL: https://webassembly.github.io/spec/web-api/
[WEBCRYPTO]
Daniel Huigens. Web Cryptography Level 2. URL: https://w3c.github.io/webcrypto/
[WEBIDL]
Edgar Chen; Timothy Gu. Web IDL 标准. 现行标准. URL: https://webidl.spec.whatwg.org/
[XHR]
Anne van Kesteren. XMLHttpRequest 标准. 现行标准. URL: https://xhr.spec.whatwg.org/

信息性参考

[PERFORMANCE-TIMELINE]
Nicolas Pena Moreno. 性能时间线. URL: https://w3c.github.io/performance-timeline/
[USER-TIMING]
Nicolas Pena Moreno. 用户时序 第3级. URL: https://w3c.github.io/user-timing/

4. 术语和定义

4.1. Web 平台

Web 平台指由 W3C、WHATWG 等组织定义,被 Web 浏览器实现的技术标准的集合。

4.2. Web 互操作运行时

任何实现本规范所列 Web 平台 API 子集的 ECMAScript 程序运行环境。

虽然该术语有意涵盖 Web 浏览器,但本规范主要聚焦于非浏览器运行时的期望。

5. 通用 API 索引

所有符合本规范的 Web 互操作运行时 都应实现以下 Web 平台 API。这些 API 应按其规范性要求实现,除非本规范有特殊说明。若符合规范的运行时环境选择(无论出于何种原因)偏离规范性要求,必须在文档中清晰、明确地说明该偏离。

所有下列接口应在通过 globalThis 可访问的全局对象上暴露,除非本规范另有说明:

所有下列方法和属性应在通过 globalThis 可访问的全局对象上暴露,除非本规范另有说明:

支持 worker 的 Web 互操作运行时还应在 worker 的 globalThis 上暴露 onerroronunhandledrejectiononrejectionhandledself ,除非本规范另有说明。[HTML]

6. 全局作用域

全局作用域(globalThis)的具体类型在不同运行时之间可能有所不同。大多数 Web 平台 API 的定义都假定 Web 浏览器环境,通常会暴露如 WindowWorkerGlobalScope 等类型。为简化一致性要求,本规范所定义的所有接口、方法和属性都应当在运行时相关的全局作用域上暴露(例如 globalThis.cryptoglobalThis.ReadableStream 等)。

在许多运行时中,新增全局作用域属性时,如果新属性与现有应用代码冲突,可能会引入破坏性变更。许多 Web 平台 API 使用 readonly 属性 来定义全局属性。[WEBIDL] 为避免破坏性变更,符合本规范的运行时可以选择忽略新增到全局作用域上的属性的 readonly 属性。这样可允许这些运行时的用户在属性与现有应用代码冲突时进行删除或覆盖。

Window 类和 worker 环境下,全局对象应始终是 EventTarget 的实例。Web 互操作运行时应遵循 报告异常算法,以及 JavaScript 的 HostPromiseRejectionTracker 宿主钩子,详见 [HTML]。这包括在全局对象上触发 errorunhandledrejectionrejectionhandled 事件。

如果因历史原因无法让全局对象成为 EventTarget 的实例,则相关事件仍应通过全局作用域下的其他合适机制触发。该机制至少应能提供如果全局对象为 EventTarget 实例时由相关事件接口提供的信息。此类运行时不应支持 onerroronunhandledrejectiononrejectionhandled 全局属性。此类运行时也不要求实现 ErrorEventPromiseRejectionEvent 接口。

注意: 例如,在 Node.js 中,全局对象并不实现 EventTarget, 相关事件会在 globalThis.process 对象上,以 uncaughtExceptionunhandledRejectionrejectionHandled 事件名触发。

7. 默认 User-Agent 值要求

默认 `User-Agent` 值的作用是使应用代码能够可靠识别其运行所处的运行时。该值应为字符串,并符合 User-Agent 的构造规范,详见 [RFC7231]

User-Agent      = product *( RWS ( product / comment ) )
product         = token ["/" product-version]
product-version = token

默认 `User-Agent` 值应被视为单一、完整、不透明和无结构的值。建议该值只包含一个 product 标记,不包含可选的 product-version,且不应包含任何 comment 组件。

注意: 例如,navigator.userAgent 可以设置为 'MyRuntime'

索引

本规范定义的术语

引用定义的术语

Ecma International

Rue du Rhone 114

CH-1204 Geneva

Tel: +41 22 849 6000

Fax: +41 22 849 6001

Web: https://ecma-international.org/

© 2025 Ecma International

This draft document may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published, and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this section are included on all such copies and derivative works. However, this document itself may not be modified in any way, including by removing the copyright notice or references to Ecma International, except as needed for the purpose of developing any document or deliverable produced by Ecma International.

This disclaimer is valid only prior to final version of this document. After approval all rights on the standard are reserved by Ecma International.

The limited permissions are granted through the standardization phase and will not be revoked by Ecma International or its successors or assigns during this time.

This document and the information contained herein is provided on an "AS IS" basis and ECMA INTERNATIONAL DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY OWNERSHIP RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Software License

All Software contained in this document ("Software") is protected by copyright and is being made available under the "BSD License", included below. This Software may be subject to third party rights (rights from parties other than Ecma International), including patent rights, and no licenses under such third party rights are granted under this license even if the third party concerned is a member of Ecma International. SEE THE ECMA CODE OF CONDUCT IN PATENT MATTERS AVAILABLE AT https://ecma-international.org/memento/codeofconduct.htm FOR INFORMATION REGARDING THE LICENSING OF PATENT CLAIMS THAT ARE REQUIRED TO IMPLEMENT ECMA INTERNATIONAL STANDARDS.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
  2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
  3. Neither the name of the authors nor Ecma International may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE ECMA INTERNATIONAL "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL ECMA INTERNATIONAL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.