Node.js v25.3.0 文档

生成单个可执行准备 blob#>

【Generating single executable preparation blobs】

可以使用要用于构建单个可执行文件的 Node.js 二进制文件的 --experimental-sea-config 标志生成注入到应用中的单个可执行文件准备 blob。该标志接收一个 JSON 格式的配置文件路径。如果传入的路径不是绝对路径，Node.js 将使用相对于当前工作目录的路径。

【Single executable preparation blobs that are injected into the application can be generated using the --experimental-sea-config flag of the Node.js binary that will be used to build the single executable. It takes a path to a configuration file in JSON format. If the path passed to it isn't absolute, Node.js will use the path relative to the current working directory.】

该配置当前读取以下顶层字段：

【The configuration currently reads the following top-level fields:】

{
  "main": "/path/to/bundled/script.js",
  "output": "/path/to/write/the/generated/blob.blob",
  "disableExperimentalSEAWarning": true, // Default: false
  "useSnapshot": false,  // Default: false
  "useCodeCache": true, // Default: false
  "execArgv": ["--no-warnings", "--max-old-space-size=4096"], // Optional
  "execArgvExtension": "env", // Default: "env", options: "none", "env", "cli"
  "assets": {  // Optional
    "a.dat": "/path/to/a.dat",
    "b.txt": "/path/to/b.txt"
  }
} 拷贝

如果路径不是绝对路径，Node.js 将使用相对于当前工作目录的路径。用于生成二进制数据的 Node.js 二进制版本必须与将注入二进制数据的版本相同。

【If the paths are not absolute, Node.js will use the path relative to the current working directory. The version of the Node.js binary used to produce the blob must be the same as the one to which the blob will be injected.】

注意：在生成跨平台 SEA（例如，在 darwin-arm64 上为 linux-x64 生成 SEA）时，必须将 useCodeCache 和 useSnapshot 设置为 false，以避免生成不兼容的可执行文件。由于代码缓存和快照只能在编译它们的平台上加载，当尝试加载在不同平台上构建的代码缓存或快照时，生成的可执行文件可能会在启动时崩溃。

【Note: When generating cross-platform SEAs (e.g., generating a SEA for linux-x64 on darwin-arm64), useCodeCache and useSnapshot must be set to false to avoid generating incompatible executables. Since code cache and snapshots can only be loaded on the same platform where they are compiled, the generated executable might crash on startup when trying to load code cache or snapshots built on a different platform.】

资源#>

【Assets】

用户可以通过在配置中添加键-路径字典作为 assets 字段来包含资源。在构建时，Node.js 会从指定路径读取资源并将它们打包到准备好的 blob 中。在生成的可执行文件中，用户可以使用 sea.getAsset() 和 sea.getAssetAsBlob() API 检索这些资源。

【Users can include assets by adding a key-path dictionary to the configuration as the assets field. At build time, Node.js would read the assets from the specified paths and bundle them into the preparation blob. In the generated executable, users can retrieve the assets using the sea.getAsset() and sea.getAssetAsBlob() APIs.】

{
  "main": "/path/to/bundled/script.js",
  "output": "/path/to/write/the/generated/blob.blob",
  "assets": {
    "a.jpg": "/path/to/a.jpg",
    "b.txt": "/path/to/b.txt"
  }
} 拷贝

单一可执行应用可以按如下方式访问资源：

【The single-executable application can access the assets as follows:】

const { getAsset, getAssetAsBlob, getRawAsset, getAssetKeys } = require('node:sea');
// Get all asset keys.
const keys = getAssetKeys();
console.log(keys); // ['a.jpg', 'b.txt']
// Returns a copy of the data in an ArrayBuffer.
const image = getAsset('a.jpg');
// Returns a string decoded from the asset as UTF8.
const text = getAsset('b.txt', 'utf8');
// Returns a Blob containing the asset.
const blob = getAssetAsBlob('a.jpg');
// Returns an ArrayBuffer containing the raw asset without copying.
const raw = getRawAsset('a.jpg'); 拷贝

有关更多信息，请参阅 sea.getAsset()、sea.getAssetAsBlob()、sea.getRawAsset() 和 sea.getAssetKeys() API 的文档。

【See documentation of the sea.getAsset(), sea.getAssetAsBlob(), sea.getRawAsset() and sea.getAssetKeys() APIs for more information.】

启动快照支持#>

【Startup snapshot support】

useSnapshot 字段可以用来启用启动快照支持。在这种情况下，当最终可执行文件启动时，main 脚本不会运行。相反，它会在构建机器上生成单个可执行应用准备 blob 时运行。生成的准备 blob 会包含一个快照，该快照捕获了由 main 脚本初始化的状态。注入准备 blob 的最终可执行文件将在运行时反序列化该快照。

【The useSnapshot field can be used to enable startup snapshot support. In this case the main script would not be when the final executable is launched. Instead, it would be run when the single executable application preparation blob is generated on the building machine. The generated preparation blob would then include a snapshot capturing the states initialized by the main script. The final executable with the preparation blob injected would deserialize the snapshot at run time.】

当 useSnapshot 为 true 时，主脚本必须调用 v8.startupSnapshot.setDeserializeMainFunction() API 来配置在最终可执行文件被用户启动时需要运行的代码。

【When useSnapshot is true, the main script must invoke the v8.startupSnapshot.setDeserializeMainFunction() API to configure code that needs to be run when the final executable is launched by the users.】

单个可执行应用使用快照的典型模式是：

【The typical pattern for an application to use snapshot in a single executable application is:】

1. 在构建时，在构建机器上，会运行主脚本以将堆初始化到准备好接收用户输入的状态。该脚本还应使用 v8.startupSnapshot.setDeserializeMainFunction() 配置一个主函数。该函数将被编译并序列化到快照中，但在构建时不会被调用。
2. 在运行时，主函数将在用户计算机上的反序列化堆之上运行，以处理用户输入并生成输出。

启动快照脚本的一般约束也适用于用于为单一可执行应用构建快照的主脚本，主脚本可以使用 v8.startupSnapshot API 来适应这些约束。详见 关于 Node.js 启动快照支持的文档。

【The general constraints of the startup snapshot scripts also apply to the main script when it's used to build snapshot for the single executable application, and the main script can use the v8.startupSnapshot API to adapt to these constraints. See documentation about startup snapshot support in Node.js.】

V8 代码缓存支持#>

【V8 code cache support】

当在配置中将 useCodeCache 设置为 true 时，在生成单个可执行文件准备 Blob 的过程中，Node.js 会编译 main 脚本以生成 V8 代码缓存。生成的代码缓存将成为准备 Blob 的一部分，并注入到最终的可执行文件中。当启动单个可执行应用时，Node.js 不会从头编译 main 脚本，而是使用代码缓存来加快编译速度，然后执行脚本，从而提高启动性能。

【When useCodeCache is set to true in the configuration, during the generation of the single executable preparation blob, Node.js will compile the main script to generate the V8 code cache. The generated code cache would be part of the preparation blob and get injected into the final executable. When the single executable application is launched, instead of compiling the main script from scratch, Node.js would use the code cache to speed up the compilation, then execute the script, which would improve the startup performance.】

注意： 当 useCodeCache 为 true 时，import() 不起作用。

执行参数#>

【Execution arguments】

execArgv 字段可用于指定 Node.js 特定的参数，这些参数将在单个可执行应用启动时自动应用。这使得应用开发者能够配置 Node.js 运行时选项，而无需终端用户了解这些标志。

【The execArgv field can be used to specify Node.js-specific arguments that will be automatically applied when the single executable application starts. This allows application developers to configure Node.js runtime options without requiring end users to be aware of these flags.】

例如，以下配置：

【For example, the following configuration:】

{
  "main": "/path/to/bundled/script.js",
  "output": "/path/to/write/the/generated/blob.blob",
  "execArgv": ["--no-warnings", "--max-old-space-size=2048"]
} 拷贝

将指示 SEA 使用 --no-warnings 和 --max-old-space-size=2048 标志启动。在可执行文件中嵌入的脚本中，可以使用 process.execArgv 属性访问这些标志：

【will instruct the SEA to be launched with the --no-warnings and --max-old-space-size=2048 flags. In the scripts embedded in the executable, these flags can be accessed using the process.execArgv property:】

// If the executable is launched with `sea user-arg1 user-arg2`
console.log(process.execArgv);
// Prints: ['--no-warnings', '--max-old-space-size=2048']
console.log(process.argv);
// Prints ['/path/to/sea', 'path/to/sea', 'user-arg1', 'user-arg2'] 拷贝

用户提供的参数位于 process.argv 数组中，从索引 2 开始，就像应用启动时会发生的情况一样：

【The user-provided arguments are in the process.argv array starting from index 2, similar to what would happen if the application is started with:】

node --no-warnings --max-old-space-size=2048 /path/to/bundled/script.js user-arg1 user-arg2 拷贝

执行参数扩展#>

【Execution argument extension】

execArgvExtension 字段控制如何提供除 execArgv 字段中指定的之外的额外执行参数。它接受以下三个字符串值之一：

【The execArgvExtension field controls how additional execution arguments can be provided beyond those specified in the execArgv field. It accepts one of three string values:】

• "none"：不允许使用扩展。只会使用 execArgv 中指定的参数，并且 NODE_OPTIONS 环境变量将被忽略。
• "env"：(默认) NODE_OPTIONS 环境变量可以扩展执行参数。这是为了保持向后兼容性的默认行为。
• cli：可执行文件可以使用 --node-options="--flag1 --flag2" 启动，这些标志将被解析为 Node.js 的执行参数，而不是传递给用户脚本。这允许使用 NODE_OPTIONS 环境变量不支持的参数。

例如，使用 "execArgvExtension": "cli" 时：

【For example, with "execArgvExtension": "cli":】

{
  "main": "/path/to/bundled/script.js",
  "output": "/path/to/write/the/generated/blob.blob",
  "execArgv": ["--no-warnings"],
  "execArgvExtension": "cli"
} 拷贝

可执行文件可以这样启动：

【The executable can be launched as:】

./my-sea --node-options="--trace-exit" user-arg1 user-arg2 拷贝

这相当于运行：

【This would be equivalent to running:】

node --no-warnings --trace-exit /path/to/bundled/script.js user-arg1 user-arg2 拷贝

在注入的主脚本中#>

【In the injected main script】

单个可执行应用 API#>

【Single-executable application API】

node:sea 内置模块允许从嵌入在可执行文件中的 JavaScript 主脚本与单一可执行应用进行交互。

【The node:sea builtin allows interaction with the single-executable application from the JavaScript main script embedded into the executable.】

sea.isSea()#>

• 返回：<boolean> 此脚本是否在单一可执行应用中运行。

sea.getAsset(key[, encoding])#>

此方法可用于检索在构建时配置为打包到单一可执行应用中的资源。找不到匹配的资源时会抛出错误。

【This method can be used to retrieve the assets configured to be bundled into the single-executable application at build time. An error is thrown when no matching asset can be found.】

• key <string> 在单个可执行应用配置中，由 assets 字段指定的字典中该资源的键。
• encoding <string> 如果指定，资源将被解码为字符串。支持 TextDecoder 的任何编码都可以。如果未指定，将返回包含资源副本的 ArrayBuffer。
• 返回：<string> | <ArrayBuffer>

sea.getAssetAsBlob(key[, options])#>

类似于 sea.getAsset()，但返回结果为 <Blob>。当找不到匹配的资源时会抛出错误。

【Similar to sea.getAsset(), but returns the result in a <Blob>. An error is thrown when no matching asset can be found.】

• key <string> 在单个可执行应用配置中，由 assets 字段指定的字典中该资源的键。
• options <Object>
  • type <string> BLOB 的可选 MIME 类型。
• 返回：<Blob>

sea.getRawAsset(key)#>

此方法可用于检索在构建时配置为打包到单一可执行应用中的资源。找不到匹配的资源时会抛出错误。

【This method can be used to retrieve the assets configured to be bundled into the single-executable application at build time. An error is thrown when no matching asset can be found.】

与 sea.getAsset() 或 sea.getAssetAsBlob() 不同，这个方法不会返回副本。相反，它返回打包在可执行文件中的原始资源。

【Unlike sea.getAsset() or sea.getAssetAsBlob(), this method does not return a copy. Instead, it returns the raw asset bundled inside the executable.】

目前，用户应避免写入返回的数组缓冲区。如果注入的部分未标记为可写或未正确对齐，写入返回的数组缓冲区很可能会导致崩溃。

【For now, users should avoid writing to the returned array buffer. If the injected section is not marked as writable or not aligned properly, writes to the returned array buffer is likely to result in a crash.】

• key <string> 在单个可执行应用配置中，由 assets 字段指定的字典中该资源的键。
• 返回：<ArrayBuffer>

sea.getAssetKeys()#>

• 返回 <string[]> 一个包含嵌入在可执行文件中的所有资源键的数组。如果没有嵌入资源，则返回一个空数组。

此方法可用于获取嵌入到单个可执行应用中的所有资源键的数组。当不在单个可执行应用中运行时，会抛出错误。

【This method can be used to retrieve an array of all the keys of assets embedded into the single-executable application. An error is thrown when not running inside a single-executable application.】

注入的主脚本中的 require(id) 不是基于文件的#>

【require(id) in the injected main script is not file based】

require() 在注入的主脚本中与非注入模块可用的 require() 不同。它也没有非注入 require() 的任何属性，除了 require.main。它只能用于加载内置模块。尝试加载只能在文件系统中找到的模块将会抛出错误。

用户可以不依赖基于文件的 require()，而是将他们的应用打包成一个独立的 JavaScript 文件，然后注入到可执行文件中。这也确保了依赖图更加确定性。

【Instead of relying on a file based require(), users can bundle their application into a standalone JavaScript file to inject into the executable. This also ensures a more deterministic dependency graph.】

但是，如果仍然需要基于文件的 require()，也可以实现：

【However, if a file based require() is still needed, that can also be achieved:】

const { createRequire } = require('node:module');
require = createRequire(__filename); 拷贝

__filename 和 module.filename 在注入的主脚本中#>

【__filename and module.filename in the injected main script】

注入的主脚本中 __filename 和 module.filename 的值等于 process.execPath。

【The values of __filename and module.filename in the injected main script are equal to process.execPath.】

注入的主脚本中的 __dirname#>

【__dirname in the injected main script】

注入的主脚本中 __dirname 的值等于 process.execPath 的目录名称。

【The value of __dirname in the injected main script is equal to the directory name of process.execPath.】

注意事项#>

【Notes】

单个可执行应用创建过程#>

【Single executable application creation process】

旨在创建单个可执行 Node.js 应用的工具必须将使用 --experimental-sea-config 准备的 blob 内容注入到:

【A tool aiming to create a single executable Node.js application must inject the contents of the blob prepared with --experimental-sea-config" into:】

• 如果 node 二进制文件是 体育 文件，则创建一个名为 NODE_SEA_BLOB 的资源
• 如果 node 二进制文件是 Mach-O 文件，则在 NODE_SEA 段中有一个名为 NODE_SEA_BLOB 的部分
• 如果 node 二进制文件是 精灵 文件，则命名为 NODE_SEA_BLOB 的注释

在二进制文件中搜索 NODE_SEA_FUSE_fce680ab2cc467b6e072b8b5df1996b2:0 保险丝 字符串，并将最后一个字符改为 1，以表示资源已被注入。

【Search the binary for the NODE_SEA_FUSE_fce680ab2cc467b6e072b8b5df1996b2:0 fuse string and flip the last character to 1 to indicate that a resource has been injected.】

平台支持#>

【Platform support】

单一可执行文件支持仅在以下平台上通过 CI 定期测试：

【Single-executable support is tested regularly on CI only on the following platforms:】

• Windows
• macOS
• Linux（除 Alpine 之外的所有发行版 由 Node.js 支持，以及除 s390x 之外的所有架构 由 Node.js 支持）

这是由于缺乏更好的工具来生成可用于在其他平台上测试此功能的单一可执行文件。

【This is due to a lack of better tools to generate single-executables that can be used to test this feature on other platforms.】

欢迎提供其他资源注入工具/工作流程的建议。请在 https://github.com/nodejs/single-executable/discussions 发起讨论，以帮助我们记录它们。