--experimental-config-file=path，--experimental-config-file

🌐 --experimental-config-file=path, --experimental-config-file

新增于: v23.10.0, v22.16.0

如果存在，Node.js 将在指定路径查找配置文件。如果未指定路径，Node.js 将在当前工作目录中查找 node.config.json 文件。要指定自定义路径，请使用 --experimental-config-file=path 形式。不支持以空格分隔的 --experimental-config-file path 形式。别名 --experimental-default-config-file 等同于没有参数的 --experimental-config-file。 Node.js 将读取配置文件并应用设置。配置文件应为具有以下结构的 JSON 文件。 vX.Y.Z 中的 $schema 必须替换为你正在使用的 Node.js 版本，或使用该主版本行的最新版本 latest-vX.x。

🌐 If present, Node.js will look for a configuration file at the specified path. If the path is not specified, Node.js will look for a node.config.json file in the current working directory. To specify a custom path, use the --experimental-config-file=path form. The space-separated --experimental-config-file path form is not supported. The alias --experimental-default-config-file is equivalent to --experimental-config-file without an argument. Node.js will read the configuration file and apply the settings. The configuration file should be a JSON file with the following structure. vX.Y.Z in the $schema must be replaced with the version of Node.js you are using or latest-vX.x for the latest version of that major release line.

{
  "$schema": "https://nodejs.cn/dist/vX.Y.Z/docs/node-config-schema.json",
  "nodeOptions": {
    "import": [
      "amaro/strip"
    ],
    "watch-path": "src",
    "watch-preserve-output": true
  },
  "test": {
    "test-isolation": "process"
  },
  "watch": {
    "watch-preserve-output": true
  }
}

配置文件支持特定于命名空间的选项：

🌐 The configuration file supports namespace-specific options:

nodeOptions 字段包含在 NODE_OPTIONS 中允许的 CLI 标志。
命名空间字段如 test、watch 和 permission 包含该子系统特定的配置。

配置文件可以使用 nodeVersion 针对特定的 Node.js 主版本：

🌐 The configuration file can target a specific Node.js major version with nodeVersion:

{
  "nodeVersion": 25,
  "nodeOptions": {
    "watch-path": "src"
  }
}

要在同一个文件中保留多个特定版本的配置，请使用 configs 数组。Node.js 将使用第一个其 nodeVersion 与当前 Node.js 主版本匹配的条目：

🌐 To keep multiple version-specific configurations in the same file, use the configs array. Node.js will use the first entry whose nodeVersion matches the current Node.js major version:

{
  "$schema": "https://nodejs.cn/dist/latest-v26.x/docs/node-config-schema.json",
  "configs": [
    {
      "nodeVersion": 25,
      "config": {
        "$schema": "https://nodejs.cn/dist/latest-v25.x/docs/node-config-schema.json",
        "nodeOptions": {
          "watch-path": "src"
        }
      }
    }
  ]
}

当使用 configs 时，顶层只能包含 $schema 和 configs。每个 configs 项必须定义一个整数 nodeVersion 和一个对象 config。单个顶层配置不需要 nodeVersion，但如果存在，它必须匹配当前的 Node.js 主版本。

🌐 When configs is used, the top level may only contain $schema and configs. Each configs item must define an integer nodeVersion and an object config. A single top-level config does not require nodeVersion, but if present it must match the current Node.js major version.

当配置文件中存在命名空间时，Node.js 会自动启用相应的标志（例如，--test、--watch、--permission）。这允许你配置特定子系统的选项，而无需在命令行上显式传递标志。

🌐 When a namespace is present in the configuration file, Node.js automatically enables the corresponding flag (e.g., --test, --watch, --permission). This allows you to configure subsystem-specific options without explicitly passing the flag on the command line.

例如：

🌐 For example:

{
  "test": {
    "test-isolation": "process"
  }
}

等同于：

🌐 is equivalent to:

node --test --test-isolation=process

要在仍使用命名空间选项的情况下禁用自动标志，你可以在命名空间中显式将标志设置为 false：

🌐 To disable the automatic flag while still using namespace options, you can explicitly set the flag to false within the namespace:

{
  "test": {
    "test": false,
    "test-isolation": "process"
  }
}

不支持无操作标志。当前并非所有 V8 标志都被支持。

🌐 No-op flags are not supported. Not all V8 flags are currently supported.

可以使用官方 JSON 模式来验证配置文件，这可能会根据 Node.js 版本的不同而有所变化。配置文件中的每个键都对应一个可以作为命令行参数传递的标志。该键的值就是将传递给该标志的值。

🌐 It is possible to use the official JSON schema to validate the configuration file, which may vary depending on the Node.js version. Each key in the configuration file corresponds to a flag that can be passed as a command-line argument. The value of the key is the value that would be passed to the flag.

例如，上面的配置文件等同于以下命令行参数：

🌐 For example, the configuration file above is equivalent to the following command-line arguments:

node --import amaro/strip --watch-path=src --watch-preserve-output --test-isolation=process

配置中的优先级如下：

🌐 The priority in configuration is as follows:

NODE_OPTIONS 和命令行选项
Dotenv NODE_OPTIONS
配置文件

配置文件中的值不会覆盖环境变量、命令行选项或由 --env-file 标志解析的 NODE_OPTIONS 环境文件中的值。

🌐 Values in the configuration file will not override the values in the environment variables, command-line options, or the NODE_OPTIONS env file parsed by the --env-file flag.

键不能在相同或不同的命名空间内重复。

🌐 Keys cannot be duplicated within the same or different namespaces.

如果配置文件包含未知的键或不能在命名空间中使用的键，配置解析器将抛出错误。

🌐 The configuration parser will throw an error if the configuration file contains unknown keys or keys that cannot be used in a namespace.

Node.js 不会对用户提供的配置进行清理或验证，所以 绝对不要 使用不可信的配置文件。

🌐 Node.js will not sanitize or perform validation on the user-provided configuration, so NEVER use untrusted configuration files.