ctx.native.node 允许扩展在 Studio 和打包后的玩家项目中使用 Node.js 内置模块,适合读写本地文件、处理路径或调用其他宿主级能力。
v1.9.2 新增

加载内置模块

使用 require() 同步加载模块:
static run(ctx) {
  const path = ctx.native.node.require<typeof import("node:path")>("node:path");
  return path.join("save-data", "profile.json");
}
需要异步写法时使用 import()
static async run(ctx) {
  const fs = await ctx.native.node.import<typeof import("node:fs/promises")>(
    "node:fs/promises",
  );
  return fs.readFile("notes.txt", "utf8");
}
两种方法都只接受带 node: 前缀的显式内置模块,例如 node:fsnode:pathnode:osnode:crypto

第三方依赖

ctx.native.node 不能加载 npm 包:
// 错误:不是显式 Node 内置模块
ctx.native.node.require("lodash");
第三方依赖需要由扩展自己的 Vite 或其他构建流程打进 dist bundle。不要依赖用户电脑上全局安装的包,也不要在运行时执行安装命令。

能力范围

扩展来源是否可用
本地扩展默认开放
项目发行物默认开放,预览与打包后的玩家项目沿用同一规则
工坊扩展账号需要取得 Node 原生扩展发布资格,且每个版本都要重新审核
提交工坊时,Studio 会检测产物是否使用 ctx.native.node。即使选择闭源,也会附带一份仅供运营审核、不会公开给用户的源码包。权限由审核结果派生,不需要在 extension.json 中手动添加。 没有权限时,调用会抛出明确错误;扩展应捕获错误并提供不依赖原生能力的降级路径。
Node 内置模块可以访问玩家电脑上的文件和系统资源。只读取功能必需的路径,不收集无关信息,不执行来自网络或玩家输入的任意代码,并在写入、覆盖或删除文件前给出清晰提示。