Trunk-rs 配置系统全面解析：从基础到高级应用

前言

Trunk-rs 作为现代化的前端构建工具，其配置系统在 0.21.0 版本经历了重大重构。本文将全面剖析 Trunk 的配置机制，帮助开发者掌握从基础配置到高级特性的完整知识体系。

配置系统架构

Trunk 采用分层配置系统，优先级从高到低依次为：

1. 命令行参数（含环境变量）
2. 配置文件设置
3. 默认配置值

这种设计既保证了灵活性，又提供了合理的默认行为。

配置文件详解

文件类型与加载机制

Trunk 支持多种配置文件格式，按以下顺序查找：

1. Trunk.toml / .trunk.toml
2. Trunk.yaml / .trunk.yaml
3. Trunk.json / .trunk.json

若未找到上述文件，则会读取 Cargo.toml 中的 package.metadata.trunk 配置节。

格式转换示例

不同格式间的配置可以相互转换，例如 TOML 配置：

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

对应的 YAML 格式为：

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

核心配置模块

构建配置（Build）

[build]
target = "index.html"       # 入口HTML文件
html_output = "index.html"  # 输出HTML文件名
release = false             # 是否启用发布模式
dist = "dist"               # 输出目录
public_url = "/"            # 资源公共路径
filehash = true             # 文件名包含哈希值
inject_scripts = true       # 自动注入脚本
offline = false             # 离线模式
minify = "never"            # 压缩策略：never/on_release/always

开发服务器（Serve）

[serve]
addresses = ["127.0.0.1"]  # 监听地址
port = 8080                # 监听端口
open = false               # 构建完成后自动打开浏览器
no_spa = false             # 禁用SPA回退
tls_key_path = "key.pem"   # TLS私钥路径
tls_cert_path = "cert.pem" # TLS证书路径

文件监控（Watch）

[watch]
watch = ["src"]   # 额外监控目录
ignore = ["temp"] # 忽略目录

代理配置（Proxy）

支持多代理配置：

[[proxy]]
backend = "https://api.example.com"
ws = true                  # 启用WebSocket
rewrite = "/api"           # 路径重写
insecure = true            # 允许自签名证书

高级特性

版本控制

从 0.19.0 开始支持版本约束：

trunk-version = ">=0.21.0"  # 版本要求语法与Cargo相同

钩子机制

支持构建生命周期钩子：

[[hooks]]
stage = "post_build"       # 阶段：pre_build/build/post_build
command = "bash"           # 执行命令
command_arguments = ["deploy.sh"] # 命令参数

环境变量与命令行

环境变量命名遵循 TRUNK_<SECTION>_<ITEM> 格式，如：

• TRUNK_SERVE_PORT=8080
• TRUNK_BUILD_RELEASE=true

命令行参数具有最高优先级，可通过 trunk serve --help 查看完整选项。

迁移指南

从 0.21.0 之前版本迁移时需注意：

1. 旧版配置字段可能已被标记为废弃
2. 新版支持更多配置文件格式
3. 旧版Trunk无法识别新版配置文件

建议逐步迁移并测试构建结果。

最佳实践

1. 项目配置优先使用 .trunk.toml（隐藏文件）
2. 团队共享配置使用 Trunk.yaml（便于版本控制）
3. 简单项目可直接使用 Cargo.toml 内嵌配置
4. 生产环境使用版本约束确保兼容性

通过合理运用Trunk的配置系统，开发者可以构建出高效、可维护的前端工作流。