深入解析 @truffle/require:在 Truffle 上下文中安全执行 JavaScript 与 TypeScript 模块

原创2026-09-21 20:46:261,958 阅读
文章标签:区块链开发工具Web3

深入解析 @truffle/require:在 Truffle 上下文中安全执行 JavaScript 与 TypeScript 模块

导读

@truffle/require 是 Truffle Suite 中负责"在 Truffle 项目上下文中加载并执行外部脚本"的核心模块。truffle exec 命令与交互式 truffle console 都依赖它运行用户脚本,脚本内可直接访问 artifacts、config、web3 等全局对象。读完本文,你将掌握 file() 与 exec() 两个 API 的用法、沙箱全局变量的完整清单、require 重定向解析机制、TypeScript 脚本的编译原理,以及该模块在 Truffle CLI 中的实际调用链。


一、模块定位:一个"带 Truffle 上下文的 require"

@truffle/require 的官方描述是"Require and execute a Javascript module within a Truffle context"(见 packages/require/README.md)。它的核心价值不在于普通的 require(),而在于:

  • 把脚本放进一个 Node vm 沙箱中执行,隔离部分全局环境;
  • 向沙箱注入 Truffle 专属的全局对象(如 artifacts、config、web3),让脚本能直接操作已编译的合约与当前网络;
  • 提供一套自定义 require 解析逻辑,使脚本内的依赖查找既尊重项目目录,又能回退到全局安装的模块;
  • 原生支持 TypeScript 脚本的即时编译(借助 ts-node)。

该模块位于 packages/require,包名为 @truffle/require(版本 2.1.43,见 package.json),主入口为 dist/index.js,源码为 TypeScript(lib/*.ts)。

在 Truffle 生态中的位置


二、核心 API:file() 与 exec()

@truffle/require 对外暴露两个函数,均定义在 lib/index.ts。

1. file(options: RequireOptions) —— 低层执行入口

file() 负责真正把一个源文件加载进沙箱并执行,返回模块的导出值。参数类型 RequireOptions 定义在 lib/types.ts:

参数 类型 说明
file string 要执行的目标源文件路径(必填)
config TruffleConfig 用户项目的 @truffle/config 配置实例
context { [key: string]: any } 附加到沙箱的任意全局变量,键名即为沙箱中的变量名
resolver Resolver @truffle/resolver 实例,会被注入到沙箱的 artifacts 全局

执行流程(对应 lib/index.ts):

  1. 将 options.file 解析为绝对路径;
  2. 用 TruffleConfig.default().with(options) 生成合并后的配置;
  3. 新建一个 Module 实例 scriptModule 作为脚本的模块容器;
  4. 构建沙箱对象(详见第三节);
  5. 把 conf.context 中的键值逐一合并进沙箱(这正是 web3、interfaceAdapter 等运行时对象的注入点);
  6. 通过 vm.createContext(sandbox) 创建沙箱上下文;
  7. 临时将进程工作目录切换到脚本所在目录(process.chdir(cwd)),执行完毕后再切回原目录;
  8. 调用 compile() 预处理源码(支持 TypeScript 转译,见第五节);
  9. new vm.Script(source, { filename }).runInContext(context) 在沙箱中执行脚本;
  10. 返回 scriptModule.exports.default ?? scriptModule.exports —— 既兼容 CommonJS 的 module.exports,也兼容 export default 风格的模块。

2. exec(options: ExecOptions, done) —— 供 CLI 使用的高层封装

exec() 是 truffle exec 命令直接调用的入口,参数类型 ExecOptions 见 lib/types.ts。它通过 expectOptions 校验以下必填项:

  • contracts_build_directory:编译产物目录
  • file:待执行脚本路径
  • resolver:合约解析器
  • provider:JSON-RPC Provider(web3 与 interface-adapter 均使用它)
  • network、networks、network_id:当前网络相关信息

exec() 的内部逻辑(lib/index.ts):

  1. 用 createInterfaceAdapter 创建接口适配器、用 Web3Shim 创建 web3 实例,两者都绑定 options.provider 与网络类型;
  2. 调用 file(),并把 { web3, interfaceAdapter } 作为 context 注入沙箱,同时透传 resolver 与 config;
  3. 约定脚本必须导出一个函数 fn,执行后调用 fn(done);done 是回调,脚本完成后调用它通知 CLI 结束。若脚本抛错,则直接 done(error) 回传错误。

注意:exec() 要求脚本导出一个函数。truffle exec 的帮助提示也强调:"all scripts must call process.exit() when finished"(见 packages/core/lib/commands/exec/run.js),即脚本执行完应主动结束进程或调用回调。


三、沙箱全局变量全览

file() 在 lib/index.ts 中构建的沙箱对象,是对 Node 全局对象的一个子集(源码注释明确引用 Node globals 文档),再加上 Truffle 专属对象:

沙箱变量 来源 用途
__filename / __dirname 脚本路径 与普通 Node 模块一致的路径语义
Buffer Node 全局 二进制数据处理
clearImmediate / clearInterval / clearTimeout Node 全局 定时器清理
console Node 全局 日志输出
exports 脚本模块 CommonJS 导出
global 宿主全局对象 访问宿主全局
process Node 全局 进程与环境信息
setImmediate / setInterval / setTimeout Node 全局 定时器
module 新建的 Module 实例 模块系统
config @truffle/config 实例 读取项目配置(网络、编译等)
artifacts @truffle/resolver 实例 加载与操作已编译合约
require 自定义函数 重定向的依赖解析(见第四节)
web3、interfaceAdapter exec() 注入的 context 链上交互(仅经 exec() 路径存在)

此外,conf.context 中的任意键都会被合并进沙箱(lib/index.ts),这为扩展全局变量提供了钩子。

TypeScript 视角的全局类型

@truffle/require 还提供了沙箱全局变量的类型声明:lib/sandboxGlobalContextTypes.ts 声明了 const config: TruffleConfig 与 const artifacts: Resolver。运行 TS 脚本时,该文件会被编译进 ts-node 编译器服务(见第五节),使 TypeScript 脚本在类型检查层面也能感知这两个全局对象。


四、自定义 require:三级解析策略

沙箱中的 require 不是 Node 原生的 require,而是一个手工实现的解析函数(lib/index.ts),其解析顺序为:

  1. 绝对路径:直接 originalRequire(id) 加载。这里使用 original-require 包(require 被 webpack 或本沙箱劫持时,仍能拿到原始 require),保证加载的是真实文件。
  2. 相对路径(id 以 . 开头):拼接为 path.join(path.dirname(sourceFilePath), id),即相对于脚本文件自身解析,与普通 Node 语义一致。
  3. 模块名(非绝对、非相对):
    • 从 conf.working_directory 出发,尝试 path.join(moduleDir, "node_modules", id);
    • 若失败,则逐级向父目录上溯(moduleDir = path.dirname(moduleDir)),直到文件系统根目录;
    • 全部失败后,最终回退到 originalRequire(id) 走全局模块解析,此时若仍找不到,则让错误自然抛出。

这套策略的意图很明确:脚本无论放在项目哪个子目录,都能找到项目本地 node_modules 中的依赖;同时也不阻断全局安装的模块(例如直接 require("path")、require("web3") 这类核心/全局模块)。

测试对三种场景的验证

测试文件 test/internal_requires.ts 将三种场景各测一遍(JS 与 TS 各一份):

  • 全局模块:require("path") 应返回与测试自身导入的 path 相同对象(module_with_global_require.js);
  • 本地文件:require("./module_with_global_require.js") 通过 __dirname 相对引用另一个脚本,并逐层返回 path 对象(module_with_local_file_require.js);
  • 本地 node_modules 模块:require("mocha"),注释明确说明"mocha 是 @truffle/require 的依赖,因此是本地的",最终断言返回的即 mocha 对象(module_with_local_module_require.js)。

TypeScript 版本使用 import 语法与 export default 导出,对应文件为 typescript_module_with_global_import.ts 等三个 *.ts 测试模块,同样验证三类解析。


五、TypeScript 支持:ts-node 编译器服务

lib/typescript.ts 提供 compile() 函数,是 TS 脚本支持的实现核心。

5.1 编译流程

  1. 用 readFileSync 读取源文件;
  2. 通过正则 /^\.(cts|tsx?)$/i 判断扩展名是否为 .ts / .tsx / .cts(lib/typescript.ts);非 TS 文件原样返回源码;
  3. 对 TS 文件,获取(或创建)一个缓存的 ts-node 编译器服务并执行编译。

5.2 编译器服务的创建与缓存

_getOrCreateCompilationService()(lib/typescript.ts)的要点:

  • 使用 originalRequire("ts-node") 加载 ts-node,确保用的是用户环境中的 ts-node 而不是本包可能误捆绑的副本;
  • 若 ts-node 未安装,抛出 TsNodeDependencyError,提示"Attempted to execute module at path ... but the 'ts-node' module, or one of its required peers has not been installed"(错误类型定义在 lib/types.ts);
  • 首次创建时传入 cwd: conf.working_directory、esm: false、compilerOptions: { inlineSourceMap: true };
  • 通过 ts-node.register() 注册,并把编译器服务实例挂在宿主 process 对象上(process[tsNode.REGISTER_INSTANCE])以便复用——注释特别说明:"我们传给子上下文的 process 实例来自宿主全局上下文",因此可以跨脚本共享同一编译器服务。

5.3 沙箱全局类型的注册方式

_compileSandboxGlobalContextTypes()(lib/typescript.ts)会把 sandboxGlobalContextTypes.ts 编译进编译器服务,从而为所有用户 TS 脚本注册 config、artifacts 两个全局类型。源码注释解释了为何选择"直接编译该文件"而非注入 triple-slash 指令或修改 compilerOptions:注入代码会造成堆栈行号偏移且每次都要重新评估全局类型;修改 files / typeRoots 又会覆盖 @types 搜索路径与用户 tsconfig.json 的配置。最终方案只在首次初始化时有一点性能开销,却能保证用户代码零侵入、配置与用户 tsconfig.json 保持一致。


六、在 Truffle CLI 中的真实调用链

6.1 truffle exec 命令

truffle exec <script> 的完整链路(packages/core/lib/commands/exec/run.js):

  1. Config.detect(options) 检测项目配置;
  2. 从 options.file 或位置参数 options._[0] 获取脚本路径,缺省则抛出配置错误;
  3. 相对路径转绝对路径;
  4. Environment.detect(config) 探测并连接网络,输出 Using network '...';
  5. 若带 --compile / -c,先经 @truffle/workflow-compile 编译并保存 artifacts;
  6. promisify(exec)(config.with({ file })) 调用 @truffle/require 的 exec(),注入 web3 后运行脚本。

典型的脚本形态如下:

// scripts/deploy.js —— 用 truffle exec 运行
module.exports = async function (done) {
  const instance = await artifacts.require("MyContract").deployed();
  console.log(await instance.name());
  done(); // 通知 CLI 脚本结束
};

6.2 交互式 console

truffle console 在 packages/core/lib/console.js 引入本模块,复用相同的沙箱上下文与全局注入逻辑,因此你在 console 里能直接使用 artifacts、web3 等全局变量,与脚本内的体验一致。


七、运行测试

本包使用 mocha 驱动测试(见 package.json 的 test 脚本:mocha --require ts-node/register --extension ts,js)。在仓库 packages/require 目录下可运行:

yarn build   # tsc 编译 + 复制 sandboxGlobalContextTypes.ts 到 dist
yarn test    # 运行 internal_requires.ts 等测试

测试断言的核心不变量是:无论脚本是 JS 还是 TS、无论依赖是全局模块、本地文件还是 node_modules 中的模块,file() 返回的模块导出都应与测试进程内 require 的同一对象严格相等(assert.equal(obj, path) / assert.equal(obj, mocha)),从而验证沙箱 require 解析与真实 Node 解析的一致性。


八、小结

@truffle/require 用不到 200 行核心源码,解决了"脚本如何在 Truffle 上下文中运行"这一关键问题:

  • 沙箱隔离 + 全局注入:file() 用 vm 沙箱执行脚本,并提供 artifacts、config、web3 等 Truffle 全局对象;
  • 三级 require 解析:绝对路径、相对脚本路径、沿 working_directory 逐级上溯的本地 node_modules,最后回退全局模块;
  • TypeScript 一等公民:通过 ts-node 编译器服务实现 .ts / .tsx / .cts 即时编译,并保持与用户 tsconfig.json 一致;
  • CLI 集成:truffle exec 与 truffle console 均建立在本模块之上。

理解该模块,就能明白为什么 Truffle 脚本可以"零配置"地访问合约与网络,也掌握了排查脚本加载问题的切入点——例如 TS 脚本报 TsNodeDependencyError,只需确保项目中安装了 ts-node 及其 peer 依赖。

登录后查看全文
truffle