深入解析 @truffle/require:在 Truffle 上下文中安全执行 JavaScript 与 TypeScript 模块
深入解析 @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 生态中的位置
- packages/core/lib/commands/exec/run.js 中
const exec = require("@truffle/require").exec;——truffle exec命令直接调用本模块; - packages/core/lib/console.js 中
const Require = require("@truffle/require");——truffle console同样复用了本模块的沙箱与全局注入能力。
二、核心 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):
- 将
options.file解析为绝对路径; - 用
TruffleConfig.default().with(options)生成合并后的配置; - 新建一个
Module实例scriptModule作为脚本的模块容器; - 构建沙箱对象(详见第三节);
- 把
conf.context中的键值逐一合并进沙箱(这正是web3、interfaceAdapter等运行时对象的注入点); - 通过
vm.createContext(sandbox)创建沙箱上下文; - 临时将进程工作目录切换到脚本所在目录(
process.chdir(cwd)),执行完毕后再切回原目录; - 调用
compile()预处理源码(支持 TypeScript 转译,见第五节); new vm.Script(source, { filename }).runInContext(context)在沙箱中执行脚本;- 返回
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):
- 用
createInterfaceAdapter创建接口适配器、用Web3Shim创建 web3 实例,两者都绑定options.provider与网络类型; - 调用
file(),并把{ web3, interfaceAdapter }作为context注入沙箱,同时透传resolver与config; - 约定脚本必须导出一个函数
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),其解析顺序为:
- 绝对路径:直接
originalRequire(id)加载。这里使用original-require包(require被 webpack 或本沙箱劫持时,仍能拿到原始 require),保证加载的是真实文件。 - 相对路径(
id以.开头):拼接为path.join(path.dirname(sourceFilePath), id),即相对于脚本文件自身解析,与普通 Node 语义一致。 - 模块名(非绝对、非相对):
- 从
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 编译流程
- 用
readFileSync读取源文件; - 通过正则
/^\.(cts|tsx?)$/i判断扩展名是否为.ts/.tsx/.cts(lib/typescript.ts);非 TS 文件原样返回源码; - 对 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):
Config.detect(options)检测项目配置;- 从
options.file或位置参数options._[0]获取脚本路径,缺省则抛出配置错误; - 相对路径转绝对路径;
Environment.detect(config)探测并连接网络,输出Using network '...';- 若带
--compile/-c,先经@truffle/workflow-compile编译并保存 artifacts; 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 依赖。