物件SandBox

隔離沙箱對象，用以管理一個獨立的運作空間

所有的程式碼都運行在自己的沙箱中，全域的require 會呼叫目前沙箱載入模組，沙箱會透過require 傳遞給載入的沙箱。下面的範例建立一個沙箱，限制只允許存取全域基礎模組中的assert模組，並添加a 和b 兩個自訂模組：

1
2
3
4
5
6
7
8
var vm = require('vm');
var sbox = new vm.SandBox({
    a: 100,
    b: 200,
    assert: require('assert')
});

var mod_in_sbox = sbox.require('./path/to/mod');

需要注意，SandBox 不是防攻擊的安全沙箱，SandBox 只是一個獨立的運作空間，可以用來隔離不同的程式碼，避免相互幹擾，但不能防止惡意程式碼。

繼承關係

建構函數

SandBox

建構一個新的隔離沙箱對象，並初始化基礎模組

1
new SandBox(Object mods = {});

呼叫參數:

• mods: Object, 指定要新增的模組物件字典

---

建構一個新的隔離沙箱對象，並初始化基礎模組

1
2
new SandBox(Object mods,
    Function require);

呼叫參數:

• mods: Object, 指定要新增的模組物件字典
• require: Function, 自訂require 函數，當模組不存在時，先呼叫自訂函數，無返回再從檔案載入

---

建構一個獨立Global 新的隔離沙箱對象，並初始化基礎模組

1
2
new SandBox(Object mods,
    Object global);

呼叫參數:

• mods: Object, 指定要新增的模組物件字典
• global: Object, 指定已初始化的Global 屬性

---

建構一個獨立Global 新的隔離沙箱對象，並初始化基礎模組

1
2
3
new SandBox(Object mods,
    Function require,
    Object global);

呼叫參數:

• mods: Object, 指定要新增的模組物件字典
• require: Function, 自訂require 函數，當模組不存在時，先呼叫自訂函數，無返回再從檔案載入
• global: Object, 指定已初始化的Global 屬性

成員屬性

global

Object, 查詢沙箱的global物件

1
readonly Object SandBox.global;

---

modules

Object, 查詢沙箱中現存的所有模組的字典對象

1
readonly Object SandBox.modules;

成員函數

addBuiltinModules

在沙箱中新增內建基礎模組

1
SandBox.addBuiltinModules();

---

add

在沙箱中新增一個基礎模組

1
2
SandBox.add(String id,
    Value mod);

呼叫參數:

• id: String, 指定要新增的模組名稱，此路徑與目前執行腳本無關，必須為絕對路徑或模組名
• mod: Value, 指定要新增的模組對象

---

在沙箱中新增一組基礎模組

1
SandBox.add(Object mods);

呼叫參數:

• mods: Object, 指定要新增的模組物件字典，新增的javascript 模組將會產生一份複製，以避免沙箱修改物件產生互相干擾

---

addScript

在沙箱中新增一個腳本模組

1
2
Value SandBox.addScript(String srcname,
    Buffer script);

呼叫參數:

• srcname: String, 指定要新增的腳本名稱，srcname 必須包含副檔名，例如json或js, jsc
• script:Buffer, 指定要新增的二進位代碼

回傳結果:

• Value, 傳回載入的模組對象

---

remove

從沙箱中刪除指定的基礎模組

1
SandBox.remove(String id);

呼叫參數:

• id: String, 指定要刪除的模組名稱，此路徑與目前執行腳本無關，必須為絕對路徑或模組名

---

has

從沙箱中偵測基礎模組是否存在

1
Boolean SandBox.has(String id);

呼叫參數:

• id: String, 指定要偵測的模組名稱，此路徑與目前執行腳本無關，必須為絕對路徑或模組名

回傳結果:

• Boolean, 是否存在

---

clone

複製目前沙箱，新沙箱包含目前沙箱的模組，以及相同的名稱和require 函數

1
SandBox SandBox.clone();

回傳結果:

• SandBox, 複製的新沙箱

---

freeze

凍結當前沙箱，凍結後的沙箱，對global所做的修改將被忽略

1
SandBox.freeze();

---

run

運行一個腳本

1
SandBox.run(String fname);

呼叫參數:

• fname: String, 指定要執行的腳本路徑，此路徑與目前執行腳本無關，必須為絕對路徑

---

resolve

查詢一個模組並傳回模組完整檔名

1
2
String SandBox.resolve(String id,
    String base);

呼叫參數:

• id: String, 指定要載入的模組名稱
• base: String, 指定查找路徑

回傳結果:

• String, 返回載入的模組完整檔名

---

require

載入一個模組並返回模組對象

1
2
Value SandBox.require(String id,
    String base);

呼叫參數:

• id: String, 指定要載入的模組名稱
• base: String, 指定查找路徑

回傳結果:

• Value, 傳回載入的模組對象

---

setModuleCompiler

對指定的extname 新增compiler, extname 不可為系統內建副檔名(包括{'.js', '.json', '.jsc', '.wasm'}), compiler 需回傳有效的javascript 腳本.

1
2
SandBox.setModuleCompiler(String extname,
    Function compiler);

呼叫參數:

• extname: String, 指定的extname, 必須以'.' 開頭, 且為非系統內建副檔名
• compiler: Function, 編譯回呼函數, 所有帶有extname 的檔案僅會require 一次. 此回呼函數格式為compiler(buf, requireInfo), buf 為讀取到的文件Buffer, requireInfo 結構為{filename: string}.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
var vm = require('vm');
var sbox = new vm.SandBox({});

// compile ts to js and load
sbox.setModuleCompiler('.ts', tsCompiler);
var mod_ts = sbox.require('./a.ts');

// compile coffee to js and load
sbox.setModuleCompiler('.coffee', cafeCompiler);
var mod_coffee = sbox.require('./a.coffee');

// compile jsx to js and load
sbox.setModuleCompiler('.jsx', reactCompiler);
var mod_react = sbox.require('./a.jsx');

// compile yaml to rest and load
sbox.setModuleCompiler('.yml', yaml2Rest)
sbox.setModuleCompiler('.yaml', yaml2Rest)

// compile markdown to html and load
sbox.setModuleCompiler('.md', mdCompiler)
sbox.setModuleCompiler('.markdown', mdCompiler)

---

toString

傳回物件的字串表示，一般回傳"[Native Object]"，物件可以根據自己的特性重新實現

1
String SandBox.toString();

回傳結果:

• String, 傳回物件的字串表示

---

toJSON

傳回物件的JSON 格式表示，一般傳回物件定義的可讀屬性集合

1
Value SandBox.toJSON(String key = "");

呼叫參數:

• key: String, 未使用

回傳結果:

• Value, 傳回包含可JSON 序列化的值