最小通用 Web API

草案,

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

介绍

有许多ECMAScript运行时环境被用于Web浏览器之外,尤其是在Web服务器和边缘平台上。这种方式的一个主要好处是能够在多个场景下使用同一种编程语言,从而减少专门化,并允许在服务器端和客户端之间重用代码。

由于在Web浏览器中运行的代码占据了ECMAScript代码的绝大多数,运行时具有支持与Web浏览器相同API的动力。然而,如果没有规定要实现哪些Web平台API,最终的环境格局将导致这些环境之间较差的互操作性。

因此,本 Ecma 标准定义了最小公用 Web API 规范,规定了服务器运行时实现以实现与 Web 互操作性的 Web 平台 API 的子集。这是该标准的第一版,对应于 2025 年的快照。随着 Web 平台和 Web 服务器运行时的发展,委员会计划以每年一次的频率发布新版。

本 Ecma 标准由技术委员会 55 制定,并于 2025 年 12 月被大会采纳。

ALTERNATIVE COPYRIGHT NOTICE AND COPYRIGHT LICENSE

© 2025 Ecma International

By obtaining and/or copying this work, you (the licensee) agree that you have read, understood, and will comply with the following terms and conditions.

Permission under Ecma’s copyright to copy, modify, prepare derivative works of, and distribute this work, with or without modification, for any purpose and without fee or royalty is hereby granted, provided that you include the following on ALL copies of the work or portions thereof, including modifications:

(i) The full text of this COPYRIGHT NOTICE AND COPYRIGHT LICENSE in a location viewable to users of the redistributed or derivative work.

(ii) Any pre-existing intellectual property disclaimers, notices, or terms and conditions. If none exist, the Ecma alternative copyright notice should be included.

(iii) Notice of any changes or modifications, through a copyright statement on the document such as “This document includes material copied from or derived from [title and URL of the Ecma document]. Copyright © Ecma International.”

Disclaimers

THIS WORK IS PROVIDED “AS IS,” AND COPYRIGHT HOLDERS MAKE NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF THE DOCUMENT WILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.

COPYRIGHT HOLDERS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE DOCUMENT.

The name and trademarks of copyright holders may NOT be used in advertising or publicity pertaining to the work without specific, written prior permission. Title to copyright in this work will at all times remain with copyright holders.

1. 范围

本标准定义了最小公用 Web API 的 2025 年快照,该 API 是由 W3C 和 WHATWG 等 Web 平台标准定义的 API 的精选子集,旨在规定基于 ECMAScript 的浏览器和 Web 服务器运行时环境的最小通用能力集。

本标准的预期受众为希望与 Web 平台兼容的 Web 服务器运行时环境。但本标准所描述的 API 集也可由任何希望实现 Web 互操作性的 ECMAScript 运行时环境实现,即使其主要用途与 Web 服务器无关。

2. 一致性

符合本标准的实现应当按照对应的 W3C 或 WHATWG 标准的定义,提供本规范中列出的接口和属性。符合本标准的实现还必须符合 ECMA-262。

符合要求的运行时可以实现针对任何 Web 平台 API 的特定扩展。这些扩展的定义应保证其使用既不与任何 Web 平台 API 的规范功能相矛盾,也不会导致其不符合规范。即使不修改现有 API 行为,扩展 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. 术语和定义

在本文档中,术语和定义以 ECMA-262、压缩标准、控制台标准、DOM 标准、编码标准、Fetch 标准、文件 API、高精度时间、HTML 标准、流标准、URL 标准、URL 模式标准、WebAssembly JavaScript 接口、WebAssembly Web API、W3C Web 加密第二级及以下内容为准。外部定义的术语在附录 A 中有出处。

4.1. Web 平台

由W3C、WHATWG等组织定义的技术标准的组合,由Web浏览器实现

4.2. Web互操作运行时

实现本标准的基于ECMAScript的运行时环境

注:Web浏览器属于Web互操作运行时。
“Web互操作运行时”一词有意定义得较为宽泛。本标准的主要关注点是Web服务器运行时。

5. 通用 API 索引

所有符合本标准的Web互操作运行时必须实现以下每一项Web 平台API。这些API应按照其规范性要求实现,但§ 6 全局作用域中另有规定的除外。如运行时环境因技术或结构原因必须与规范性要求不一致,则需提供清晰的文档说明,文档应包括偏差的解释和影响。

注:例如,由于Web服务器运行时没有origin概念,它们必须违背[FETCH]要求的在网络请求中添加 Origin首部。

5.1. 通用接口

以下所有接口必须在可通过globalThis访问的全局对象上暴露。

[DOM]中定义的接口:

[HTML]中定义的接口:

[WEBIDL]中定义的接口:

[FETCH]中定义的接口:

[XHR]中定义的接口:

[FILEAPI]中定义的接口:

[COMPRESSION]中定义的接口:

[STREAMS]中定义的接口:

[ENCODING]中定义的接口:

[URL]中定义的接口:

[URLPATTERN]中定义的接口:

[WEBCRYPTO]中定义的接口:

[HR-TIME]中定义的接口:

[WASM-JS-API-2]中定义的接口:

5.2. 通用方法和属性

以下所有方法和属性必须在可通过globalThis访问的全局对象上暴露,§ 6 全局作用域中另有规定的除外。

[HTML]中定义的方法和属性:

[FETCH]中定义的方法和属性:

[CONSOLE]中定义的方法和属性:

[WEBCRYPTO]中定义的方法和属性:

[HR-TIME]中定义的方法和属性:

[WASM-JS-API-2]中定义的方法和属性:

5.3. Web worker

本标准不要求运行时支持web worker。但是,如果运行时拥有全局作用域,且该作用域映射到WorkerGlobalScope (见§ 6 全局作用域),则全局对象须按[HTML]中的定义暴露如下事件处理器和属性,但§ 6 全局作用域中另有规定的除外。

6. 全局作用域

全局作用域(globalThis)的具体类型在不同运行时间可以不同。多数Web平台API的定义假设Web浏览器环境会特别提供诸如 WindowWorkerGlobalScope 等类型。为简化一致性要求,本标准并不要求支持此类全局作用域接口,但相关运行时的每个全局作用域可以映射为Web规范定义的某个全局作用域接口。本标准要求由Web规范要求在全局作用域接口上暴露的所有接口、方法和属性,都要暴露在运行时对应的全局作用域(如globalThis.cryptoglobalThis.ReadableStream等)上。

注:运行时的主全局作用域应映射为Window,Web worker全局作用域应映射为WorkerGlobalScope等。不映射为具体定义全局接口的全局作用域,只能实现[Exposed=*]定义的Web API。

在许多运行时中,添加新的全局作用域属性时,如果新全局与现有应用代码冲突,可能引入破坏性变更。许多Web平台API通过只读(readonly属性)定义全局属性。为避免引入破坏性变更,符合本标准的运行时在向全局作用域添加属性时可以不实现readonly属性,这允许用户在属性与应用代码冲突时,能够删除或覆盖这些属性。

当全局对象对应于WindowWorkerGlobalScope 全局接口时,应当是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.