介绍
除了网页浏览器之外,ECMAScript 运行时环境的应用范围非常广泛,尤其是在 Web 服务器和边缘平台。采用这种方式的一个主要好处是可以在多个环境中使用同一种编程语言,从而减少专业化,并允许在服务器端和客户端之间复用代码。
由于在网页浏览器中运行的代码占据了 ECMAScript 代码的绝大部分,运行时环境通常会被激励去支持与网页浏览器相同的 API。然而,如果没有规定应实现哪些 Web 平台 API,最终就会导致这些环境之间的互操作性较差。
因此,本 Ecma 标准定义了最小公用 Web API 规范,规定了服务器运行时实现以实现与 Web 互操作性的 Web 平台 API 的子集。这是该标准的第一版,对应于 2025 年的快照。随着 Web 平台和 Web 服务器运行时的发展,委员会计划以每年一次的频率发布新版。
本 Ecma 标准由技术委员会 55 制定,并于 2025 年 12 月被大会采纳。
Copyright
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 等组织定义并由网页浏览器实现的技术标准组合
4.2. Web 互操作运行时
实现本标准的基于 ECMAScript 的运行时环境
注意:网页浏览器是 Web 互操作运行时。
“Web 互操作运行时”这一术语本身定义较为宽泛。本标准主要关注 Web 服务器端运行时。
5. 通用 API 索引
所有符合本标准的Web 兼容运行时都应实现以下每个Web 平台 API。这些 API 应当根据其规范性要求实现,除非在§ 6 全局作用域中另有规定。如任何运行时环境因技术或结构性原因必须偏离规范性要求,须提供明确的文档说明,文档应包括偏离的解释及其影响。
注意:例如,由于 Web 服务器运行时没有源(origin)的概念,因此它们必须违反[FETCH]标准中在网络请求中添加Origin头的要求。
以下所有接口都应通过globalThis暴露在全局对象上:
除§ 6 全局作用域中另有规定外,下列所有方法和属性应通过globalThis暴露在全局对象上:
-
globalThis.clearTimeout()[HTML] -
globalThis.clearInterval()[HTML] -
globalThis.crypto[WEBCRYPTO] -
globalThis.onunhandledrejection[HTML] -
globalThis.onrejectionhandled[HTML] -
globalThis.performance[HR-TIME] -
globalThis.queueMicrotask()[HTML] -
globalThis.reportError()[HTML] -
globalThis.setTimeout()[HTML] -
globalThis.setInterval()[HTML] -
globalThis.structuredClone()[HTML] -
globalThis.WebAssembly.compile()[WASM-JS-API-2] -
globalThis.WebAssembly.compileStreaming()[WASM-WEB-API-2] -
globalThis.WebAssembly.instantiate()[WASM-JS-API-2] -
globalThis.WebAssembly.instantiateStreaming()[WASM-WEB-API-2] -
globalThis.WebAssembly.JSTag[WASM-JS-API-2] -
globalThis.WebAssembly.validate()[WASM-JS-API-2]
本标准不要求运行时必须支持 web worker。
但是,如果某个运行时拥有可映射到 WorkerGlobalScope
的全局作用域(详见 § 6 全局作用域),那么其全局对象也应暴露 onerror、
onunhandledrejection、
onrejectionhandled
以及
self,
除非 § 6 全局作用域 中另有规定。[HTML]
6. 全局作用域
全局作用域(globalThis)的具体类型可能因运行时而异。大多数 Web 平台 API 的定义假定 Web 浏览器环境,并明确暴露 Window、
WorkerGlobalScope
等类型。为简化一致性要求,本标准不要求必须支持这些全局作用域接口,但每个相关运行时中的全局作用域都可以映射到 web 规范中定义的全局作用域接口。所有由本标准定义且被 web
规范要求在全局作用域接口中暴露的接口、方法和属性,都应在运行时对应的全局作用域上暴露(例如
globalThis.crypto、globalThis.ReadableStream 等)。
注意: 预计运行时的主全局作用域会映射为 Window,
web worker 全局作用域会映射为 WorkerGlobalScope
等。不能映射到任何全局接口的全局作用域,只能实现定义为 [Exposed=*]
的 web API。
在许多运行时中,向全局作用域添加新属性可能带来兼容性破坏,如果新增的全局属性与现有应用代码冲突。许多 Web 平台 API 使用 readonly
属性来定义全局属性。[WEBIDL]。为避免引入破坏性变更,符合本标准的运行时可以省略给全局作用域新增属性时的
readonly,允许用户删除或覆盖这些属性,以避免与现有应用冲突。
当全局对象对应 Window
或 WorkerGlobalScope
全局接口时,它应为 EventTarget
的实例。Web 兼容运行时应遵循 报告异常(report an exception) 算法,以及 JavaScript 的 HostPromiseRejectionTracker
主机钩子的定义(详见 [HTML])。这些包括在全局对象上触发
error、
unhandledrejection
和 rejectionhandled
等事件。
对于因兼容历史原因不能让全局对象成为 EventTarget
实例的情形,相关事件仍应通过全局作用域可用的其他适当机制触发。该机制至少应提供与相关事件接口同等信息,就像该全局对象为 EventTarget
时一样。此类运行时不得支持 onerror、
onunhandledrejection
以及 onrejectionhandled
全局属性,也不要求实现 ErrorEvent
和 PromiseRejectionEvent
接口。
注意: 比如在 Node.js 中,全局对象不是 EventTarget,
相关事件会在 globalThis.process 对象上以 uncaughtException、unhandledRejection 和
rejectionHandled 为事件名触发。
7. 默认 User-Agent 值要求
默认 `User-Agent` 值的作用是使应用代码能够可靠识别其运行所处的运行时。该值应为字符串,并符合
的构造规范,详见 [RFC7231]:User-Agent
User-Agent = product *( RWS ( product / comment ) ) product = token ["/" product-version] product-version = token
应用代码应将默认的 `User-Agent` 值视为单一、完整、不透明、无结构的值。建议该值只包含一个
product 标记,不包含可选的 product-version。该值不应包含任何 comment 组件。
注意: 例如,navigator.userAgent 可以设置为
'MyRuntime'。
索引
本规范定义的术语
- Web 互操作运行时, 在 § 4.2
- Web 平台, 在 § 4.1
引用定义的术语
-
[COMPRESSION] 定义如下术语:
- CompressionStream
- DecompressionStream
-
[CONSOLE] 定义如下术语:
- console
-
[DOM] 定义如下术语:
- AbortController
- AbortSignal
- CustomEvent
- Event
- EventTarget
- origin
-
[ECMASCRIPT] 定义如下术语:
- globalThis
-
[ENCODING] 定义如下术语:
- TextDecoder
- TextDecoderStream
- TextEncoder
- TextEncoderStream
-
[FETCH] 定义如下术语:
- Headers
- Request
- Response
- default `User-Agent` value
- fetch(input)
-
[FILEAPI] 定义如下术语:
- Blob
- File
-
[HR-TIME] 定义如下术语:
- Performance
- performance
-
[HTML] 定义如下术语:
- ErrorEvent
- MessageChannel
- MessageEvent
- MessagePort
- PromiseRejectionEvent
- Window
- WorkerGlobalScope
- atob(data)
- btoa(data)
- clearInterval(id)
- clearTimeout(id)
- error
- navigator
- onerror (for GlobalEventHandlers)
- onerror (for WorkerGlobalScope)
- onrejectionhandled (for WindowEventHandlers)
- onrejectionhandled (for WorkerGlobalScope)
- onunhandledrejection (for WindowEventHandlers)
- onunhandledrejection (for WorkerGlobalScope)
- queueMicrotask(callback)
- rejectionhandled
- report an exception
- reportError(e)
- self (for Window)
- self (for WorkerGlobalScope)
- setInterval(handler, timeout, ...arguments)
- setTimeout(handler, timeout, ...arguments)
- structuredClone(value, options)
- unhandledrejection
- userAgent
- web worker
-
[STREAMS] 定义如下术语:
- ByteLengthQueuingStrategy
- CountQueuingStrategy
- ReadableByteStreamController
- ReadableStream
- ReadableStreamBYOBReader
- ReadableStreamBYOBRequest
- ReadableStreamDefaultController
- ReadableStreamDefaultReader
- TransformStream
- TransformStreamDefaultController
- WritableStream
- WritableStreamDefaultController
- WritableStreamDefaultWriter
-
[URL] 定义如下术语:
- URL
- URLSearchParams
-
[URLPATTERN] 定义如下术语:
- URLPattern
-
[WASM-JS-API-2] 定义如下术语:
- CompileError
- Exception
- Global
- Instance
- JSTag
- LinkError
- Memory
- Module
- RuntimeError
- Table
- Tag
- WebAssembly
- compile(bytes)
- instantiate(bytes)
- validate(bytes)
-
[WASM-WEB-API-2] 定义如下术语:
- compileStreaming(source)
- instantiateStreaming(source)
-
[WEBCRYPTO] 定义如下术语:
- Crypto
- CryptoKey
- SubtleCrypto
- crypto
-
[WEBIDL] 定义如下术语:
- DOMException
- Exposed
- read only
-
[XHR] 定义如下术语:
- FormData
Copyright & Software License
Ecma International
Rue du Rhone 114
CH-1204 Geneva
Tel: +41 22 849 6000
Fax: +41 22 849 6001
Web: https://ecma-international.org/
Copyright Notice
© 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:
- Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
- 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.
- 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.