配置

重要提示

Trunk 的配置在 0.21.0 版本中发生了巨大变化。目标不是破坏任何东西,但这可能还是发生了。此外,分层系统现在的工作方式也略有不同。

文档也可能仍然只提到 Trunk.toml。如果是这种情况,那么现在这也包括所有其他配置文件变体。

Trunk 支持分层配置系统。基础来自合理的默认设置,然后被配置文件覆盖,再被命令行参数覆盖。

从技术上讲,存在一个项目配置结构,它具有合理的默认值。Trunk 将尝试找到一个配置文件,并将其加载到此结构中。然后,它将使用来自命令行解析器的设置(包括环境变量)覆盖此配置。

配置文件

Trunk 将尝试找到一个配置文件。可以是在本地目录中,也可以使用全局参数 --config,它可以接受文件或目录。如果参数是文件,则将直接使用此文件。否则,Trunk 将加载找到的第一个文件,搜索以下文件:

  • Trunk.toml
  • .trunk.toml
  • Trunk.yaml
  • .trunk.yaml
  • Trunk.json
  • .trunk.json

如果未找到这些文件,Trunk 将使用 Cargo.toml 中的元数据,默认为空元数据集合。

配置文件的目录将成为项目根目录,所有相对文件都将基于该项目根目录解析。

格式

Trunk 的配置仅限于 JSON 兼容模型。这意味着您可以轻松地在这些不同格式之间进行转换。

例如,具有以下 Trunk.toml 配置

[build]
dist = "dist"
[serve]
port = 8080

在 YAML 中将是以下内容

build:
  dist: "dist"
serve:
  port: 8080

此外,Cargo.toml 也基于该模型。但是,它将数据向下移动到 package.metadata.trunk 部分。上面的示例将变为

[package.metadata.trunk.build]
dist = "dist"
[package.metadata.trunk.serve]
port = 8080

命令行参数(和环境变量)

命令行参数可以覆盖部分配置。并非所有配置方面都可以通过命令行参数覆盖。命令行参数包括使用环境变量。

Trunk 在所有命令和子命令级别上都支持 --help。这将向您显示可用的选项,以及要使用的环境变量的名称。

所有相对路径都将根据项目根目录解析,项目根目录通过加载配置进行评估。

从 pre 0.21.0 迁移到向前发展的最佳方法

虽然目标是支持 Trunk.toml、命令行参数以及环境变量中的所有字段,但这仍然是一个破坏 API 的版本。在某些情况下,这样做意义不大,因此这些字段被标记为“已弃用”。它们今天会触发警告,并可能在接下来的版本之一中删除。

理想情况下,您无需更改任何内容。在某些理想情况下,您甚至不需要任何配置。如果您需要配置,现在您有了更多选择。您可以继续使用 TOML,您可以使用 .trunk.* 变体将其隐藏起来。您可以使用 YAML 或 JSON 来利用生成的 JSON 模式。或者,如果您喜欢将所有内容都放在 Cargo.toml 中,那也没问题。选择权在您手中。

重要提示

但是,当使用旧版本的 Trunk 时,您需要注意。如果您将旧版本的 Trunk(0.21.0 之前)与使用较新配置文件的项目一起使用,则该版本将不会考虑这些文件,并且可能会考虑默认设置,因为缺少 Trunk.toml 文件。

所需版本

0.19.0-alpha.2 开始,可以强制要求使用特定版本的 trunk 构建项目。

随着新功能添加到 trunk 中,这可能有助于确保构建当前版本的 trunk 实际上能够做到这一点。这可以使用 trunk-version(或使用别名 trunk_version)在 Trunk.toml 文件的级别完成。

版本格式是“版本要求”,与您可能从 Cargo 的依赖项版本字段中了解到的格式相同。

这也支持预发布版本要求,允许尽早采用即将推出的功能。

注意

0.19.0-alpha.2 之前的版本目前不支持此检查,因此它们目前会静默忽略此类错误。