QT Tool

Appearance

配置说明 ​

配置文件是 QT Tool 的核心，通过配置文件可以定义 ZIP 文件的解压规则和输出路径。

配置文件位置 ​

QT Tool 按以下优先级查找配置文件：

  1. 通过 --config 参数指定的路径
  2. 当前目录下的 config.toml

配置文件结构 ​

基本结构 ​

toml
[server]
addr = "127.0.0.1:9999"

[[output]]
name = "配置名称"
description = "配置描述"
base_path = "./output"
format = ["dir1", "dir2", "dir3"]
zip_format = ["pattern1", "pattern2", "pattern3"]
format_limit = [".png", ".svg"]

配置验证 ​

⚠️ 重要提示：配置文件会在服务器启动时进行验证，任何错误都会导致启动失败。

服务器配置 ​

server 节 ​

toml
[server]
addr = "127.0.0.1:9999"
参数类型必填默认值说明
addrstring是127.0.0.1:9999服务器监听地址

地址格式 ​

  • IPv4: 127.0.0.1:9999
  • 主机名: localhost:9999

输出配置 ​

output 节 ​

每个 [[output]] 块定义一组输出规则。

toml
[[output]]
name = "配置名称"
description = "配置描述"
base_path = "./output"
format = ["dir1", "dir2", "dir3"]
zip_format = ["pattern1", "pattern2", "pattern3"]
format_limit = [".png", ".svg"]

参数说明 ​

参数类型必填说明
namestring是配置名称，用于日志和显示
descriptionstring是配置描述，用于前端快速了解配置
base_pathstring是输出根目录
formatarray是输出路径列表（相对 base_path）
zip_formatarray是ZIP 文件匹配规则列表
format_limitarray是允许的文件扩展名

format 参数 ​

format 决定最终文件的输出路径。

输出路径计算公式：

base_path / format[i] / <文件名>

示例：

toml
base_path = "./android"
format = ["mdpi", "hdpi", "xhdpi"]

对于文件 icon.png，输出路径为：

./android/mdpi/icon.png
./android/hdpi/icon.png
./android/xhdpi/icon.png

zip_format 参数 ​

zip_format 描述 ZIP 文件内部的结构，用于匹配文件。

⚠️ 重要规则：

  • format 和 zip_format 的长度必须相等
  • 顺序必须一一对应
  • format[i] 的文件来自 zip_format[i] 匹配的文件

匹配模式 ​

1. 目录映射模式 ​

匹配 ZIP 中指定目录下的文件。

规则： 以 / 结尾的字符串表示目录

示例：

toml
zip_format = [
    "mipmap-mdpi/",
    "mipmap-hdpi/",
    "mipmap-xhdpi/"
]

匹配规则：

  • 匹配：mipmap-mdpi/icon.png
  • 匹配：a/b/mipmap-mdpi/icon.png
  • 不匹配：mipmap-mdpi.png（是文件不是目录）

完整配置示例：

toml
[[output]]
name = "Android 图标"
description = "Android 应用图标"
base_path = "./android"
format = ["mdpi", "hdpi", "xhdpi"]
zip_format = ["mipmap-mdpi/", "mipmap-hdpi/", "mipmap-xhdpi/"]
format_limit = [".png", ".svg"]

2. 同级通配模式 ​

使用通配符匹配同级文件。

规则：

  • ./ 表示 ZIP 根目录
  • ** 表示文件名通配
  • 后缀匹配按长度降序执行（避免 .png 抢匹配 @2x.png）

示例：

toml
zip_format = ["./**.png", "./**@2x.png", "./**@3x.png"]

匹配规则：

  • 匹配：icon.png
  • 匹配：icon@2x.png
  • 匹配：icon@3x.png
  • 匹配：images/header.png（任何深度）

完整配置示例：

toml
[[output]]
name = "iOS 图标"
description = "iOS 应用图标"
base_path = "./ios"
format = ["1x", "2x", "3x"]
zip_format = ["./**.png", "./**@2x.png", "./**@3x.png"]
format_limit = [".png", ".svg"]

3. 精确文件匹配 ​

匹配 ZIP 中精确路径的文件。

示例：

toml
zip_format = ["icon.png", "icon@2x.png", "icon@3x.png"]

匹配规则：

  • 匹配：icon.png
  • 匹配：icon@2x.png
  • 不匹配：images/icon.png（路径不同）

完整配置示例：

toml
[[output]]
name = "精确匹配示例"
description = "精确匹配文件"
base_path = "./output"
format = ["dir1", "dir2", "dir3"]
zip_format = ["1.png", "2.png", "3.png"]
format_limit = [".png"]

format_limit 参数 ​

format_limit 定义允许输出的文件类型白名单，用于防止恶意文件注入。

示例：

toml
format_limit = [".png", ".svg"]

作用：

  • 只允许 .png 和 .svg 文件输出
  • ZIP 中包含的其他文件类型将被忽略

安全建议：

  • 始终设置 format_limit
  • 只包含必要的文件类型
  • 避免使用 .* 等宽泛匹配

完整配置示例 ​

示例 1：Android 应用图标 ​

toml
[[output]]
name = "Android 应用图标"
description = "Android 应用图标"
base_path = "./android/app/src/main/res"
format = ["mipmap-mdpi", "mipmap-hdpi", "mipmap-xhdpi", "mipmap-xxhdpi"]
zip_format = [
    "mipmap-mdpi/",
    "mipmap-hdpi/",
    "mipmap-xhdpi/",
    "mipmap-xxhdpi/"
]
format_limit = [".png"]

示例 2：iOS 应用图标 ​

toml
[[output]]
name = "iOS 应用图标"
description = "iOS 应用图标"
base_path = "./ios/Assets.xcassets/AppIcon.appiconset"
format = ["", "@2x", "@3x"]
zip_format = ["./**.png", "./**@2x.png", "./**@3x.png"]
format_limit = [".png"]

示例 3：Web 响应式图片 ​

toml
[[output]]
name = "Web 响应式图片"
description = "Web 不同尺寸的图片"
base_path = "./assets/images"
format = ["1x", "2x", "3x", "4x"]
zip_format = [
    "./**.png",
    "./**@2x.png",
    "./**@3x.png",
    "./**@4x.png"
]
format_limit = [".png", ".jpg", ".webp"]

示例 4：Flutter 资源 ​

toml
[[output]]
name = "Flutter 资源"
description = "Flutter 项目资源"
base_path = "./assets/images"
format = ["1.0x", "2.0x", "3.0x"]
zip_format = [
    "./**.png",
    "./**@2x.png",
    "./**@3x.png"
]
format_limit = [".png", ".svg"]

配置索引 ​

⚠️ 重要提示：

  • 每个 [[output]] 块都有一个索引（从 0 开始）
  • 索引由配置文件中的位置决定
  • 修改配置块的顺序会影响索引
  • 历史记录依赖索引，请谨慎调整顺序

获取索引的方法：

bash
# 获取所有配置
curl http://127.0.0.1:9999/process/configs

# 返回数组的下标就是索引

最佳实践：

  1. 新增配置时追加到末尾
  2. 不要中间插入或删除配置
  3. 如需修改配置，保持位置不变
  4. 未来版本将支持 key-based 标识

配置验证规则 ​

服务器启动时会验证以下规则：

  1. 每个 output 块的 name 不能为空
  2. 每个 output 块的 base_path 不能为空
  3. 每个 output 块的 format 不能为空
  4. 每个 output 块的 zip_format 不能为空
  5. format 和 zip_format 的长度必须相等
  6. format_limit 的长度必须大于 0
  7. base_path 指定的目录必须存在

验证失败的示例：

toml
# 错误：name 为空
[[output]]
name = ""
description = "描述"
base_path = "./output"
format = ["dir1"]
zip_format = ["pattern1"]
format_limit = [".png"]
toml
# 错误：format 和 zip_format 长度不一致
[[output]]
name = "测试"
description = "描述"
base_path = "./output"
format = ["dir1", "dir2"]
zip_format = ["pattern1"]
format_limit = [".png"]

配置最佳实践 ​

1. 命名规范 ​

toml
# 推荐：清晰的名称
name = "Android 应用图标"
name = "iOS 启动图"
name = "Web Banner"

# 不推荐：模糊的名称
name = "图标"
name = "图片"

2. 描述信息 ​

toml
# 推荐：详细的描述
description = "Android 应用主图标，需要包含 mdpi/hdpi/xhdpi/xxhdpi 四种尺寸"

# 不推荐：简单的描述
description = "图标"

3. 路径组织 ​

toml
# 推荐：使用相对路径
base_path = "./android/app/src/main/res"

# 不推荐：使用绝对路径
base_path = "/home/user/project/android/app/src/main/res"

4. 安全配置 ​

toml
# 推荐：限制文件类型
format_limit = [".png", ".svg"]

5. 维护索引 ​

toml
# 推荐：追加新配置
[[output]]
name = "新配置"
# ... 其他配置

# 不推荐：中间插入配置
[[output]]
name = "新配置"  # 这会影响后续配置的索引

故障排除 ​

1. 配置文件加载失败 ​

错误信息：

错误: 配置项 1 的名称不能为空

解决方法： 检查配置文件格式，确保所有必填字段都有值。

2. 目录不存在 ​

错误信息：

错误: 配置（Android 图标）不存在目录：./android

解决方法： 创建指定的目录或修改 base_path 为已存在的目录。

3. 格式不匹配 ​

错误信息：

错误: 配置项 1 的格式和压缩格式长度不一致

解决方法： 确保 format 和 zip_format 的数组长度相等。

4. ZIP 文件不匹配 ​

错误信息：

错误: ZIP 文件内容格式与配置文件（Android 图标）不符合

解决方法： 检查 ZIP 文件内部结构是否与 zip_format 规则匹配。

下一步 ​

Released under the MIT License.

Copyright © 2026-present su_xii