Task 配置完全指南:掌握 `.taskrc.yml` 配置文件与优先级合并机制

原创2026-09-20 20:41:521,611 阅读
文章标签:构建工具开发工具CLI

Task 配置完全指南:掌握 .taskrc.yml 配置文件与优先级合并机制

Task 是一个以 Make 为灵感、面向现代工作流设计的跨平台构建工具。除了每个项目根目录下的 Taskfile.yml(定义"做什么任务"),Task 还提供了一套独立的配置体系 —— .taskrc.yml 配置文件(定义"Task 自身如何运行")。本文以官方 Configuration Reference 为主体,结合仓库中 taskrc/ 包的源码实现,系统讲解配置文件的查找顺序、合并规则、全部可用配置项(含 remote 远程 Taskfile 子配置),以及配置与环境变量、命令行参数的优先级关系,让你能够精确控制 verbose、silent、颜色输出、并发度、失败快速终止、实验特性开关等行为。

三种配置来源与优先级总览

Task 支持三种配置方式,它们按照以下顺序依次解析,优先级最高者最后生效:

  1. 配置文件(.taskrc.yml / .taskrc.yaml 等)—— 本文主角
  2. 环境变量(所有 Task 专属变量以 TASK_ 为前缀)
  3. 命令行参数

例如:某选项在配置文件里是 verbose: true,在环境变量里是 TASK_VERBOSE=0,在命令行里是 task build -v,最终生效的是命令行参数的值。更精确地说,environment.md 中给出的优先级链条是:

CLI 参数 > 环境变量 > 配置文件 > 内置默认值

这一设计让用户可以"默认值打底 → 配置文件全局/项目定制 → 环境变量按 CI 场景覆盖 → 命令行临时覆盖",四层叠加而互不干扰。

配置文件查找顺序(File Precedence)

Task 会自动在以下目录中查找配置文件,优先级最高的目录最先被搜索:

  1. 当前目录(或由 --taskfile / --entrypoint 参数指定的目录)
  2. 从当前目录(或上述参数指定目录)逐级向上遍历每一级目录,直到到达用户主目录或所在驱动器根目录
  3. 用户的 $HOME 目录
  4. $XDG_CONFIG_HOME/task 目录

也就是说,越靠近项目、越"贴近当前工作目录"的配置,优先级越高;而 XDG 全局配置优先级最低。这符合"项目级配置覆盖用户级配置,用户级配置覆盖系统级配置"的直觉。

文件命名规则

  • 当前目录、各级父目录以及主目录中的配置文件命名为:.taskrc.yml 或 .taskrc.yaml(带点前缀);
  • $XDG_CONFIG_HOME/task 目录下的配置文件命名相同但不带点前缀:taskrc.yml 或 taskrc.yaml。

上述文件名在源码中有直接对应:taskrc/taskrc.go 中定义了两个文件名集合:

defaultXDGTaskRCs = []string{"taskrc.yml", "taskrc.yaml"}
defaultTaskRCs    = []string{".taskrc.yml", ".taskrc.yaml"}

合并(Merge)机制

所有配置文件会被合并为一份统一配置:从优先级最低的 $XDG_CONFIG_HOME/task 文件开始,后续每一个文件如果设置了某值,就覆盖先前文件的对应值。

文档给出了一个经典三文件示例。假设存在:

# 优先级最低的全局配置
option_1: foo
option_2: foo
option_3: foo
option_1: bar
option_2: bar
# 优先级最高的项目配置
option_1: baz

合并结果:

option_1: baz # 取自 $HOME/path/to/project/.taskrc.yml
option_2: bar # 取自 $HOME/.taskrc.yml
option_3: foo # 取自 $XDG_CONFIG_HOME/task/.taskrc.yml

源码视角:合并是如何实现的

从源码结构看,配置加载的完整调用链在 taskrc/taskrc.go 的 GetConfig(dir) 函数中:它先读取 XDG 配置,再读取 $HOME 配置,然后通过 fsext.SearchAll 向上收集从给定目录到主目录路径上的所有 .taskrc.yml,最后用 slices.Reverse 反转顺序(保证子目录文件覆盖父目录文件),逐一调用 config.Merge(localConfig) 完成合并。

合并的具体语义定义在 taskrc/ast/taskrc.go 的 TaskRC.Merge 方法中,其核心原则是:非 nil 字段优先取后合并进来的值(cmp.Or(other.X, t.X))。值得注意的细节:

  • trusted-hosts 的合并是追加去重而非覆盖:先拼接两个列表,再排序并 slices.Compact 去重;
  • experiments 的合并是 map 级 maps.Copy,即键级别覆盖、无冲突键共存;
  • 列表字段(如 trusted-hosts)为空或 nil 时不会覆盖已有列表。

这些行为在 taskrc/taskrc_test.go 中有大量测试佐证,例如 TestGetConfig_All 验证了三层配置文件合并后 FOO=3, BAR=2, BAZ=1 的结果,TestGetConfig_RemoteTrustedHostsMerge 验证了 trusted-hosts 在 XDG/Home/Local 三级配置间的追加合并语义。

配置项全解(Configuration Options)

所有配置项写入 YAML 文件,键名与源码 taskrc/ast/taskrc.go 中 TaskRC 结构体的 yaml 标签一一对应(verbose、silent、color、disable-fuzzy、concurrency、interactive、remote、failfast、temp-dir、experiments)。

experiments

开启 Task 的实验性功能开关。该配置项的键不做逐一枚举,具体特性请参考 experiments 文档。其值通常是数字,代表实验提案编号:

experiments:
  feature_name: 1
  another_feature: 2

从源码看,Experiments 的类型是 map[string]int,合并时按 key 逐个覆盖。实验特性遵循"提案 → 草案 → 候选 → 稳定 → 发布"的生命周期,随时可能被修改或移除,不建议在生产环境使用。实验特性的三种开启方式中,写 .taskrc.yml(项目级、可提交到版本库)比环境变量 TASK_X_*(一次性或 dotfile 级)更适合团队共享。

verbose

  • 类型:boolean
  • 默认值:false
  • 作用:对所有任务启用详细(verbose)输出
  • CLI 等价参数:-v, --verbose
  • 环境变量:TASK_VERBOSE
verbose: true

silent

  • 类型:boolean
  • 默认值:false
  • 作用:禁止回显将要执行的命令(只显示命令输出,不显示命令本身)
  • CLI 等价参数:-s, --silent
  • 环境变量:TASK_SILENT
silent: true

color

  • 类型:boolean
  • 默认值:true
  • 作用:是否启用彩色输出。在 CI 环境(CI=true)下颜色会被自动启用
  • CLI 等价参数:-c, --color
  • 环境变量:TASK_COLOR
color: false

如果你需要精细控制各输出元素的颜色,可参考 environment.md 中的 TASK_COLOR_* 系列变量(如 TASK_COLOR_RED 默认 31、TASK_COLOR_BRIGHT_CYAN 默认 96 等),它们支持 ANSI 转义码乃至 8-bit 256 色与 RGB 前景色写法。

disable-fuzzy

  • 类型:boolean
  • 默认值:false
  • 作用:禁用任务名的模糊匹配。开启后,当你拼错任务名时,Task 不再提示相似的候选任务名(即不再输出 "Did you mean 'build'?" 之类的建议)
  • CLI 等价参数:--disable-fuzzy
  • 环境变量:TASK_DISABLE_FUZZY
disable-fuzzy: true

CLI 文档中给出了对照效果:task buidl 默认会提示是否意指 build;加上 --disable-fuzzy 后则只报 "Task 'buidl' does not exist"。

concurrency

  • 类型:integer
  • 最小值:1
  • 作用:限制同时运行的任务数量(控制并发任务数)
  • CLI 等价参数:-C, --concurrency
  • 环境变量:TASK_CONCURRENCY
concurrency: 4

注意 CLI 手册中 -C, --concurrency <number> 的语义为"限制并发任务数量,0 表示不限制",而配置文件层面的最小值为 1。该配置与 task --parallel 并行执行多个任务、以及依赖任务的并发调度共同作用。

failfast

  • 类型:boolean
  • 默认值:false
  • 作用:当某个依赖任务失败时,立即停止继续执行其余依赖任务(快速失败)
  • CLI 等价参数:-F, --failfast
  • 环境变量:TASK_FAILFAST
failfast: true

在并发/依赖场景下,默认行为是所有依赖任务继续跑完并汇总失败;开启 failfast 后则可第一时间止损。

interactive

  • 类型:boolean
  • 默认值:false
  • 作用:对缺失的必需变量(required variables)以交互式提示代替直接失败。开启后,Task 会对任何缺失的必需变量显示交互式输入提示;需要 TTY 环境,Task 会自动检测非 TTY 环境(如 CI 流水线)并跳过提示
  • CLI 等价参数:--interactive
interactive: true

该选项常与任务定义中的 requires(必需变量声明)配合使用,也常与 -y/--yes(自动回答 yes)形成对照。它没有对应的独立环境变量,但可以通过 CLI 的 --interactive 或 TASK_INTERACTIVE 环境变量触发。

temp-dir

  • 类型:string
  • 默认值:./.task
  • 作用:Task 存放临时文件的目录,例如**校验和(checksums)**与临时元数据。相对路径是相对于根 Taskfile 所在目录(而非当前工作目录)
  • 环境变量:TASK_TEMP_DIR
temp-dir: .task

TASK_TEMP_DIR 的值可以是相对路径(如 tmp/task)、绝对路径(如 /tmp/.task)或 ~/.task。默认 .task 目录正是 Task 缓存源码指纹、实现增量构建(up-to-date 判定)的核心位置。

remote(远程 Taskfile 配置)

remote 是一个对象类型配置,用于控制远程 Taskfile(通过 URL 或 Git 仓库引用并下载的 Taskfile)的获取行为。远程 Taskfile 从源码结构看由 taskfile/node_git.go 与 taskfile/node_http.go 等节点实现加载,以下配置项分别对应其安全性、缓存与 TLS 认证策略。

remote.insecure

  • 类型:boolean
  • 默认值:false
  • 作用:允许在拉取远程 Taskfile 时使用不安全连接(跳过 TLS 校验)
  • CLI 等价参数:--insecure
  • 环境变量:TASK_REMOTE_INSECURE
remote:
  insecure: true

remote.offline

  • 类型:boolean
  • 默认值:false
  • 作用:以离线模式运行,禁止拉取远程 Taskfile(必须使用本地缓存)
  • CLI 等价参数:--offline
  • 环境变量:TASK_REMOTE_OFFLINE
remote:
  offline: true

remote.timeout

  • 类型:string
  • 默认值:10s
  • 取值格式:^[0-9]+(ns|us|µs|ms|s|m|h)$(Go duration 格式)
  • 作用:远程操作的超时时间,例如 '30s'、'5m'
  • CLI 等价参数:--timeout
  • 环境变量:TASK_REMOTE_TIMEOUT
remote:
  timeout: '1m'

remote.cache-expiry

  • 类型:string
  • 默认值:0s(不缓存)
  • 取值格式:同 timeout,^[0-9]+(ns|us|µs|ms|s|m|h)$
  • 作用:远程 Taskfile 的缓存过期时间,例如 '1h'、'24h'
  • CLI 等价参数:--expiry
  • 环境变量:TASK_REMOTE_CACHE_EXPIRY
remote:
  cache-expiry: '6h'

remote.cache-dir

  • 类型:string
  • 默认值:.task
  • 作用:远程 Taskfile 的缓存目录。可以是绝对路径(如 /var/cache/task),也可以是相对于 Taskfile 目录的路径
  • CLI 等价参数:--remote-cache-dir
  • 环境变量:TASK_REMOTE_CACHE_DIR
remote:
  cache-dir: ~/.task

remote.trusted-hosts

  • 类型:array of strings
  • 默认值:[](空列表)
  • 作用:受信任主机列表。列表中的主机在下载远程 Taskfile 时不会弹出确认提示
  • CLI 等价参数:--trusted-hosts
  • 环境变量:TASK_REMOTE_TRUSTED_HOSTS(逗号分隔)
remote:
  trusted-hosts:
    - github.com
    - gitlab.com
    - raw.githubusercontent.com
    - example.com:8080

安全注意:trusted-hosts 中的主机在首次下载或校验和变化时都会自动被信任,不再提示确认。主机匹配包含端口号(如果 URL 中指定了端口)。请谨慎使用,只添加你完全信任的主机。

也可以直接在命令行指定受信任主机:

# 仅本次执行信任特定主机
task --trusted-hosts github.com -t https://github.com/user/repo.git//Taskfile.yml

# 信任多个主机(逗号分隔)
task --trusted-hosts github.com,gitlab.com -t https://github.com/user/repo.git//Taskfile.yml

# 信任带特定端口的主机
task --trusted-hosts example.com:8080 -t https://example.com:8080/Taskfile.yml

从合并逻辑看,多个配置文件中的 trusted-hosts 会取并集去重(见前文 Merge 分析),因此你可以在 XDG 级放常用主机、在项目级补充私有 Git 服务器地址,两者共存。

remote.cacert

  • 类型:string
  • 默认值:""
  • 作用:自定义 CA 证书文件路径,用于 TLS 校验(例如企业内网自签 CA)
remote:
  cacert: '/path/to/ca.crt'

remote.cert

  • 类型:string
  • 默认值:""
  • 作用:客户端证书文件路径,用于 mTLS 双向认证
remote:
  cert: '/path/to/client.crt'

remote.cert-key

  • 类型:string
  • 默认值:""
  • 作用:客户端证书私钥文件路径(与 cert 配套使用)
remote:
  cert-key: '/path/to/client.key'

完整示例配置

下面是一份覆盖所有可用选项的 .taskrc.yml 完整示例(来自官方文档):

# 全局设置
verbose: true
silent: false
color: true
disable-fuzzy: false
concurrency: 2
temp-dir: .task
remote:
  insecure: false
  offline: false
  timeout: '30s'
  cache-expiry: '24h'
  cache-dir: ~/.task
  trusted-hosts:
    - github.com
    - gitlab.com
  cacert: ''
  cert: ''
  cert-key: ''

# 开启实验特性
experiments:
  GENTLE_FORCE: 1

实战建议

  • 区分两个 YAML 文件:.taskrc.yml 配置"Task 工具本身的行为"(输出、并发、远程下载策略等),而 Taskfile.yml 定义"要执行的任务"。两者职责不同,不要混淆。
  • 善用优先级分层:把通用偏好(如 verbose、color)放在 $HOME/.taskrc.yml,把团队规范(如 concurrency、failfast、实验开关)放在仓库内 .taskrc.yml 并提交版本库;CI 中需要临时覆盖时,用 TASK_* 环境变量或 CLI 参数即可。
  • 远程 Taskfile 安全基线:生产环境建议保持 insecure: false 与 offline: false 默认值;对内网自签证书使用 cacert 而不是关闭校验;trusted-hosts 只添加完全可信的主机,因为校验和变化也不会再触发确认。
  • 排查优先级问题:如果某个选项"不生效",优先检查是不是被更高优先级来源覆盖 —— 按 配置文件 → TASK_* 环境变量 → CLI 参数 的顺序逐层排查,必要时用 task --verbose 观察实际加载结果。

延伸阅读

登录后查看全文
task