Contextify 项目技术文档

1. 安装指南

1.1 环境要求

• Node.js 版本：0.10 及以下（对于 Node.js 0.12 及以上版本，建议使用原生 vm 模块）。
• 确保已安装 node-gyp 的依赖项，具体安装步骤请参考 node-gyp 安装指南。
• 对于 Windows 用户，请参考 Windows 安装指南。

1.2 安装步骤

1. 打开终端或命令行工具。
2. 运行以下命令安装 Contextify：

   npm install contextify
   

2. 项目的使用说明

2.1 概述

Contextify 是一个用于将对象转换为 V8 执行上下文的模块。通过 Contextify，您可以将一个对象作为全局 this 来执行 JavaScript 代码。Contextify 提供了三个方法：run(code, filename)、getGlobal() 和 dispose()。

2.2 基本用法

以下是 Contextify 的基本用法示例：

var Contextify = require('contextify');
var sandbox = { console : console, prop1 : 'prop1'};
Contextify(sandbox);
sandbox.run('console.log(prop1);');
sandbox.dispose(); // 释放为上下文分配的资源

2.3 异步函数支持

Contextify 允许异步函数在上下文中继续执行，这是与 Node.js 原生 vm 模块的主要区别。以下是一个异步函数的示例：

var sandbox = Contextify({setTimeout : setTimeout});
sandbox.run("setTimeout(function () { x = 3; }, 5);");
console.log(sandbox.x); // 打印 undefined
setTimeout(function () {
    console.log(sandbox.x); // 打印 3
    sandbox.dispose();
}, 10);

3. 项目 API 使用文档

3.1 Contextify([sandbox])

• 参数：
  • sandbox：要上下文化的对象。如果不指定，将创建一个空对象。
• 返回值：返回上下文化的对象。

3.2 run(code, [filename])

• 参数：
  • code：要执行的 JavaScript 代码字符串。
  • filename：可选的文件名，用于调试。
• 功能：在上下文化的对象上下文中执行代码。

3.3 getGlobal()

• 返回值：返回 V8 上下文的实际全局对象。
• 功能：获取实际的全局对象，该对象在大多数情况下与上下文化的对象相同。

3.4 dispose()

• 功能：释放为 V8 上下文分配的内存。调用此方法后，上下文化的对象将不再安全使用。

4. 项目安装方式

4.1 使用 npm 安装

npm install contextify

4.2 手动构建

如果您需要手动构建项目，可以使用以下命令：

node-gyp rebuild

5. 测试

Contextify 使用 nodeunit 进行测试。您可以通过以下命令运行测试：

nodeunit test/

6. 注意事项

• 对于 Node.js 0.12 及以上版本，建议使用原生 vm 模块。
• 确保在不再需要上下文时调用 dispose() 方法，以避免内存泄漏。