- assert 断言
- async_hooks 异步钩子
- async_hooks/context 异步上下文
- buffer 缓冲区
- C++插件
- C/C++插件(使用Node-API)
- C++嵌入器
- child_process 子进程
- cluster 集群
- CLI 命令行
- console 控制台
- Corepack 核心包
- crypto 加密
- crypto/webcrypto 网络加密
- debugger 调试器
- deprecation 弃用
- dgram 数据报
- diagnostics_channel 诊断通道
- dns 域名服务器
- domain 域
- Error 错误
- events 事件触发器
- fs 文件系统
- global 全局变量
- http 超文本传输协议
- http2 超文本传输协议2.0
- https 安全超文本传输协议
- inspector 检查器
- Intl 国际化
- module 模块
- module/cjs CommonJS模块
- module/esm ECMAScript模块
- module/package 包模块
- net 网络
- os 操作系统
- path 路径
- perf_hooks 性能钩子
- permission 权限
- process 进程
- punycode 域名代码
- querystring 查询字符串
- readline 逐行读取
- repl 交互式解释器
- report 诊断报告
- sea 单个可执行应用程序
- stream 流
- stream/web 网络流
- string_decoder 字符串解码器
- test 测试
- timers 定时器
- tls 安全传输层
- trace_events 跟踪事件
- tty 终端
- url 网址
- util 实用工具
- v8 引擎
- vm 虚拟机
- wasi 网络汇编系统接口
- worker_threads 工作线程
- zlib 压缩
Node.js v20.7.0 文档
- Node.js v20.7.0
- ► 目录
-
►
导航
- assert 断言
- async_hooks 异步钩子
- async_hooks/context 异步上下文
- buffer 缓冲区
- C++插件
- C/C++插件(使用Node-API)
- C++嵌入器
- child_process 子进程
- cluster 集群
- CLI 命令行
- console 控制台
- Corepack 核心包
- crypto 加密
- crypto/webcrypto 网络加密
- debugger 调试器
- deprecation 弃用
- dgram 数据报
- diagnostics_channel 诊断通道
- dns 域名服务器
- domain 域
- Error 错误
- events 事件触发器
- fs 文件系统
- global 全局变量
- http 超文本传输协议
- http2 超文本传输协议2.0
- https 安全超文本传输协议
- inspector 检查器
- Intl 国际化
- module 模块
- module/cjs CommonJS模块
- module/esm ECMAScript模块
- module/package 包模块
- net 网络
- os 操作系统
- path 路径
- perf_hooks 性能钩子
- permission 权限
- process 进程
- punycode 域名代码
- querystring 查询字符串
- readline 逐行读取
- repl 交互式解释器
- report 诊断报告
- sea 单个可执行应用程序
- stream 流
- stream/web 网络流
- string_decoder 字符串解码器
- test 测试
- timers 定时器
- tls 安全传输层
- trace_events 跟踪事件
- tty 终端
- url 网址
- util 实用工具
- v8 引擎
- vm 虚拟机
- wasi 网络汇编系统接口
- worker_threads 工作线程
- zlib 压缩
- ► 其他版本
目录
WebAssembly 系统接口 (WASI)#
源代码: lib/wasi.js
WASI API 提供了 WebAssembly 系统接口 规范的实现。 WASI 让沙盒化的 WebAssembly 应用通过一系列类似 POSIX 的函数访问底层操作系统。
import { readFile } from 'node:fs/promises';
import { WASI } from 'wasi';
import { argv, env } from 'node:process';
const wasi = new WASI({
version: 'preview1',
args: argv,
env,
preopens: {
'/sandbox': '/some/real/path/that/wasm/can/access',
},
});
const wasm = await WebAssembly.compile(
await readFile(new URL('./demo.wasm', import.meta.url)),
);
const instance = await WebAssembly.instantiate(wasm, wasi.getImportObject());
wasi.start(instance);
'use strict';
const { readFile } = require('node:fs/promises');
const { WASI } = require('wasi');
const { argv, env } = require('node:process');
const { join } = require('node:path');
const wasi = new WASI({
version: 'preview1',
args: argv,
env,
preopens: {
'/sandbox': '/some/real/path/that/wasm/can/access',
},
});
(async () => {
const wasm = await WebAssembly.compile(
await readFile(join(__dirname, 'demo.wasm')),
);
const instance = await WebAssembly.instantiate(wasm, wasi.getImportObject());
wasi.start(instance);
})();
要运行上面的示例,则新建一个名为 demo.wat
的 WebAssembly 文本格式文件:
(module
;; Import the required fd_write WASI function which will write the given io vectors to stdout
;; The function signature for fd_write is:
;; (File Descriptor, *iovs, iovs_len, nwritten) -> Returns number of bytes written
(import "wasi_snapshot_preview1" "fd_write" (func $fd_write (param i32 i32 i32 i32) (result i32)))
(memory 1)
(export "memory" (memory 0))
;; Write 'hello world\n' to memory at an offset of 8 bytes
;; Note the trailing newline which is required for the text to appear
(data (i32.const 8) "hello world\n")
(func $main (export "_start")
;; Creating a new io vector within linear memory
(i32.store (i32.const 0) (i32.const 8)) ;; iov.iov_base - This is a pointer to the start of the 'hello world\n' string
(i32.store (i32.const 4) (i32.const 12)) ;; iov.iov_len - The length of the 'hello world\n' string
(call $fd_write
(i32.const 1) ;; file_descriptor - 1 for stdout
(i32.const 0) ;; *iovs - The pointer to the iov array, which is stored at memory location 0
(i32.const 1) ;; iovs_len - We're printing 1 string stored in an iov - so one.
(i32.const 20) ;; nwritten - A place in memory to store the number of bytes written
)
drop ;; Discard the number of bytes written from the top of the stack
)
)
使用 wabt 编译 .wat
到 .wasm
wat2wasm demo.wat
类:WASI
#
WASI
类提供了 WASI 系统调用 API 和其他方便的方法来使用基于 WASI 的应用。 每个 WASI
实例代表一个不同的沙箱环境。 出于安全考虑,每个 WASI
实例都必须显式地配置其命令行参数、环境变量、以及沙箱目录结构。
new WASI([options])
#
options
<Object>args
<Array> WebAssembly 应用将视为命令行参数的字符串数组。 第一个参数是 WASI 命令本身的虚拟路径。 默认值:[]
。env
<Object> 类似于process.env
的对象,WebAssembly 应用将其视为其环境。 默认值:{}
。preopens
<Object> 此对象表示 WebAssembly 应用的沙箱目录结构。preopens
的字符串键被视为沙箱中的目录。preopens
中对应的值是宿主机上这些目录的真实路径。returnOnExit
<boolean> 默认情况下,当 WASI 应用调用__wasi_proc_exit()
wasi.start()
时,将返回指定的退出代码,而不是终止进程。 将此选项设置为false
将导致 Node.js 进程以指定的退出代码退出。 默认值:true
。stdin
<integer> 在 WebAssembly 应用中用作标准输入的文件描述符。 默认值:0
。stdout
<integer> 在 WebAssembly 应用中用作标准输出的文件描述符。 默认值:1
。stderr
<integer> 在 WebAssembly 应用中用作标准错误的文件描述符。 默认值:2
。version
<string> 请求的 WASI 版本。 目前唯一支持的版本是unstable
和preview1
。 此选项是强制性的。
wasi.getImportObject()
#
如果除了 WASI 提供的那些之外不需要其他 WASM 导入,则返回一个可以传递给 WebAssembly.instantiate()
的导入对象。
如果将版本 unstable
传递给构造函数,它将返回:
{ wasi_unstable: wasi.wasiImport }
如果将版本 preview1
传递给构造函数或未指定版本,它将返回:
{ wasi_snapshot_preview1: wasi.wasiImport }
wasi.start(instance)
#
instance
<WebAssembly.Instance>
尝试通过调用 _start()
导出来开始执行 instance
作为 WASI 命令。 如果 instance
不包含 _start()
导出,或者 instance
包含 _initialize()
导出,则抛出异常。
start()
要求 instance
导出名为 memory
的 WebAssembly.Memory
。 如果 instance
没有 memory
导出,则抛出异常。
如果 start()
被多次调用,则抛出异常。
wasi.initialize(instance)
#
instance
<WebAssembly.Instance>
尝试通过调用 _initialize()
导出(如果存在)将 instance
初始化为 WASI 反应器。 如果 instance
包含 _start()
导出,则抛出异常。
initialize()
要求 instance
导出名为 memory
的 WebAssembly.Memory
。 如果 instance
没有 memory
导出,则抛出异常。
如果 initialize()
被多次调用,则抛出异常。
wasi.wasiImport
#
wasiImport
是实现 WASI 系统调用 API 的对象。 此对象应在 WebAssembly.Instance
实例化期间作为 wasi_snapshot_preview1
导入传入。