NNext.js 中文网 GitHub

Edge Runtime

Edge Runtime 的 API 参考。

Next.js 提供两种可在应用程序中使用的服务端运行时:

  • Node.js Runtime(默认),它可访问所有 Node.js API,用于渲染你的应用程序。
  • Edge Runtime,它包含更有限的API 集合,用于 Proxy。

注意事项#

  • Edge Runtime 不支持所有 Node.js API。某些包可能无法按预期工作。
  • Edge Runtime 不支持增量静态再生成(ISR)。
  • 两种运行时都可以支持流式渲染,具体取决于你的部署适配器。

参考#

Edge Runtime 支持以下 API:

网络 API#

API描述
Blob表示一个 blob
fetch获取资源
FetchEvent表示一个 fetch 事件
File表示一个文件
FormData表示表单数据
Headers表示 HTTP 标头
Request表示一个 HTTP 请求
Response表示一个 HTTP 响应
URLSearchParams表示 URL 搜索参数
WebSocket表示一个 websocket 连接

编码 API#

API描述
atob解码 base-64 编码的字符串
btoa将字符串编码为 base-64
TextDecoder将 Uint8Array 解码为字符串
TextDecoderStream可链接的流解码器
TextEncoder将字符串编码为 Uint8Array
TextEncoderStream可链接的流编码器

流 API#

API描述
ReadableStream表示一个可读流
ReadableStreamBYOBReader表示 ReadableStream 的读取器
ReadableStreamDefaultReader表示 ReadableStream 的读取器
TransformStream表示一个转换流
WritableStream表示一个可写流
WritableStreamDefaultWriter表示 WritableStream 的写入器

加密 API#

API描述
crypto提供对平台加密功能的访问
CryptoKey表示一个加密密钥
SubtleCrypto提供对常见加密原语的访问,如哈希、签名、加密或解密

Web 标准 API#

API描述
AbortController允许你在需要时中止一个或多个 DOM 请求
Array表示一组值的数组
ArrayBuffer表示通用的、固定长度的原始二进制数据缓冲区
Atomics以静态方法提供原子操作
BigInt表示任意精度的整数
BigInt64Array表示 64 位有符号整数的类型化数组
BigUint64Array表示 64 位无符号整数的类型化数组
Boolean表示逻辑实体,可以有两个值:true 和 false
clearInterval取消先前由 setInterval() 调用建立的定时重复操作
clearTimeout取消先前由 setTimeout() 调用建立的定时重复操作
console提供对浏览器调试控制台的访问
DataView表示 ArrayBuffer 的通用视图
Date以与平台无关的格式表示某一时刻
decodeURI解码先前由 encodeURI 或类似方法创建的统一资源标识符(URI)
decodeURIComponent解码先前由 encodeURIComponent 或类似方法创建的统一资源标识符(URI)组件
DOMException表示 DOM 中发生的错误
encodeURI通过将某些字符的每个实例替换为表示该字符 UTF-8 编码的一个、两个、三个或四个转义序列来编码统一资源标识符(URI)
encodeURIComponent通过将某些字符的每个实例替换为表示该字符 UTF-8 编码的一个、两个、三个或四个转义序列来编码统一资源标识符(URI)组件
Error表示尝试执行语句或访问属性时发生的错误
EvalError表示与全局函数 eval() 相关的错误
Float32Array表示 32 位浮点数的类型化数组
Float64Array表示 64 位浮点数的类型化数组
Function表示一个函数
Infinity表示数学上的 Infinity 值
Int8Array表示 8 位有符号整数的类型化数组
Int16Array表示 16 位有符号整数的类型化数组
Int32Array表示 32 位有符号整数的类型化数组
Intl提供对国际化和本地化功能的访问
isFinite确定一个值是否为有限数
isNaN确定一个值是否为 NaN
JSON提供在 JavaScript 值与 JSON 格式之间转换的功能
Map表示值的集合,其中每个值只能出现一次
Math提供对数学函数和常量的访问
Number表示一个数值
Object表示作为所有 JavaScript 对象基础的对象
parseFloat解析字符串参数并返回浮点数
parseInt解析字符串参数并返回指定基数的整数
Promise表示异步操作的最终完成(或失败)及其结果值
Proxy表示用于为基本操作(如属性查找、赋值、枚举、函数调用等)定义自定义行为的对象
queueMicrotask将微任务排队等待执行
RangeError表示值不在允许值的集合或范围内时发生的错误
ReferenceError表示引用不存在的变量时发生的错误
Reflect提供用于可拦截的 JavaScript 操作的方法
RegExp表示正则表达式,使你可以匹配字符组合
Set表示值的集合,其中每个值只能出现一次
setInterval以固定的时间延迟重复调用函数
setTimeout在指定的毫秒数后调用函数或计算表达式
SharedArrayBuffer表示通用的、固定长度的原始二进制数据缓冲区
String表示字符序列
structuredClone创建值的深拷贝
Symbol表示一种唯一且不可变的数据类型,用作对象属性的键
SyntaxError表示尝试解释语法无效的代码时发生的错误
TypeError表示值不是预期类型时发生的错误
Uint8Array表示 8 位无符号整数的类型化数组
Uint8ClampedArray表示限制在 0-255 范围内的 8 位无符号整数的类型化数组
Uint32Array表示 32 位无符号整数的类型化数组
URIError表示以错误方式使用全局 URI 处理函数时发生的错误
URL表示提供用于创建对象 URL 的静态方法的对象
URLPattern表示一个 URL 模式
URLSearchParams表示键/值对的集合
WeakMap表示键为弱引用的键/值对集合
WeakSet表示对象的集合,其中每个对象只能出现一次
WebAssembly提供对 WebAssembly 的访问

Next.js 特定的 Polyfill#

环境变量#

你可以使用 process.env 访问 next dev 和 next build 的环境变量。

不支持的 API#

Edge Runtime 有一些限制,包括:

  • 原生 Node.js API 不受支持。例如,你不能读写文件系统。
  • node_modules 可以使用,只要它们实现 ES Modules 且不使用原生 Node.js API。
  • 直接调用 require 是不允许的。请改用 ES Modules。

以下 JavaScript 语言特性被禁用,将无法工作:

API描述
eval计算以字符串表示的 JavaScript 代码
new Function(evalString)使用作为参数提供的代码创建一个新函数
WebAssembly.compile从缓冲区源编译 WebAssembly 模块
WebAssembly.instantiate从缓冲区源编译并实例化 WebAssembly 模块

在极少数情况下,你的代码可能包含(或导入)一些动态代码求值语句,这些语句在运行时无法到达,且无法通过摇树优化移除。 你可以通过 Proxy 配置放宽检查,以允许特定文件:

proxy.ts
export const config = {
  unstable_allowDynamic: [
    // 允许单个文件
    '/lib/utilities.js',
    // 使用通配符允许 function-bind 第三方模块中的所有内容
    '**/node_modules/function-bind/**',
  ],
}

unstable_allowDynamic 是一个 glob 或 glob 数组,用于忽略特定文件的动态代码求值。这些 glob 相对于你的应用程序根目录。

请注意,如果这些语句在 Edge 上执行,它们将抛出错误并导致运行时错误。

Next.js 中文网