Go Task 中文文档

Appearance

Taskfile 结构参考 ​

本文档详细介绍了 Taskfile 结构版本 3 的所有可用属性和类型，基于 官方 JSON 结构。

根结构 ​

根 Taskfile 结构定义了主 Taskfile.yml 的结构。

version ​

  • 类型: string 或 number
  • 必需: 是
  • 有效值: "3"、3 或任何有效的 semver 字符串
  • 描述: Taskfile 结构的版本
yaml
version: '3'

output ​

  • 类型: string 或 object
  • 默认值: interleaved
  • 选项: interleaved、group、prefixed
  • 描述: 控制任务输出的显示方式
yaml
# 简单字符串格式
output: group

# 高级对象格式
output:
  group:
    begin: "::group::{{.TASK}}"
    end: "::endgroup::"
    error_only: false

method ​

  • 类型: string
  • 默认值: checksum
  • 选项: checksum、timestamp、none
  • 描述: 检查任务是否为最新的默认方法
yaml
method: timestamp

includes ​

  • 类型: map[string]Include
  • 描述: 包含其他 Taskfile
yaml
includes:
  # 简单字符串格式
  docs: ./Taskfile.yml

  # 完整对象格式
  backend:
    taskfile: ./backend
    dir: ./backend
    optional: false
    flatten: false
    internal: false
    aliases: [api]
    excludes: [internal-task]
    vars:
      SERVICE_NAME: backend
    checksum: abc123...

vars ​

  • 类型: map[string]Variable
  • 描述: 对所有任务可用的全局变量
yaml
vars:
  # 简单值
  APP_NAME: myapp
  VERSION: 1.0.0
  DEBUG: true
  PORT: 8080
  FEATURES: [auth, logging]

  # 动态变量
  COMMIT_HASH:
    sh: git rev-parse HEAD

  # 变量引用
  BUILD_VERSION:
    ref: VERSION

  # 映射变量
  CONFIG:
    map:
      database: postgres
      cache: redis

env ​

  • 类型: map[string]Variable
  • 描述: 全局环境变量
yaml
env:
  NODE_ENV: production
  DATABASE_URL:
    sh: echo $DATABASE_URL

tasks ​

  • 类型: map[string]Task
  • 描述: 任务定义
yaml
tasks:
  # 简单字符串格式
  hello: echo "Hello World"

  # 数组格式
  build:
    - go mod tidy
    - go build ./...

  # 完整对象格式
  deploy:
    desc: 部署应用
    cmds:
      - ./scripts/deploy.sh

silent ​

  • 类型: bool
  • 默认值: false
  • 描述: 默认情况下抑制任务名称和命令输出
yaml
silent: true

dotenv ​

  • 类型: []string
  • 描述: 从 .env 文件加载环境变量
yaml
dotenv:
  - .env
  - .env.local

run ​

  • 类型: string
  • 默认值: always
  • 选项: always、once、when_changed
  • 描述: 任务的默认执行行为
yaml
run: once

interval ​

  • 类型: string
  • 默认值: 100ms
  • 模式: ^[0-9]+(?:m|s|ms)$
  • 描述: 监听文件更改的间隔时间
yaml
interval: 1s

set ​

  • 类型: []string
  • 选项: allexport、a、errexit、e、noexec、n、noglob、f、 nounset、u、xtrace、x、pipefail
  • 描述: 所有命令的 POSIX shell 选项
yaml
set: [errexit, nounset, pipefail]

shopt ​

  • 极型: []string
  • 选项: expand_aliases、globstar、nullglob
  • 描述: 所有命令的 Bash shell 选项
yaml
shopt: [globstar]

包含 (Include) ​

包含外部 Taskfile 的配置。

taskfile ​

  • 类型: string
  • 必需: 是
  • 描述: 要包含的 Taskfile 路径或目录
yaml
includes:
  backend: ./backend/Taskfile.yml
  # 上述的简写形式
  frontend: ./frontend

dir ​

  • 类型: 极ring
  • 描述: 包含任务的工作目录
yaml
includes:
  api:
    taskfile: ./api
    dir: ./极i

optional ​

  • 类型: bool
  • 默认值: false
  • 描述: 包含文件不存在时不报错
yaml
includes:
  optional-tasks:
    taskfile: ./optional.yml
    optional: true

flatten ​

  • 类型: bool
  • 默认值: false
  • 描述: 不添加命名空间前缀地包含任务
yaml
includes:
  common:
    taskfile: ./common.yml
    flatten: true

internal ​

  • 类型: bool
  • 默认值: false
  • 描述: 从命令行和 --list 中隐藏包含的任务
yaml
includes:
  internal:
    taskfile: ./internal.yml
    internal: true

aliases ​

  • 类型: []string
  • 描述: 命名空间的替代名称
yaml
includes:
  database:
    taskfile: ./db.yml
    aliases: [db, data]

excludes ​

  • 类型: []string
  • 描述: 包含时要排除的任务
yaml
includes:
  shared:
    taskfile: ./shared.yml
    excludes: [internal-setup, debug-only]

vars ​

  • 类型: map[string]Variable
  • 描述: 要传递给包含的 Taskfile 的变量
yaml
includes:
  deploy:
    taskfile: ./deploy.yml
    vars:
      ENVIRONMENT: production

checksum ​

  • 类型: string
  • 描述: 被包含文件的预期校验和
yaml
includes:
  remote:
    taskfile: https://example.com/tasks.yml
    checksum: c153e97e0b3a998a7ed2e61064c6ddaddd0de0c525feefd6bba8569827d8efe9

变量 (Variable) ​

变量支持多种类型，可以是静态值、动态命令、引用或映射。

静态变量 ​

yaml
vars:
  # 字符串
  APP_NAME: myapp
  # 数字
  PORT: 8080
  # 布尔值
  DEBUG: true
  # 数组
  FEATURES: [auth, logging, metrics]
  # 空值
  OPTIONAL_VAR: null

动态变量 (sh) ​

yaml
vars:
  COMMIT_HASH:
    sh: git rev-parse HEAD
  BUILD_TIME:
    sh: date -u +"%Y-%m-%dT%H:%M:%SZ"

变量引用 (ref) ​

yaml
vars:
  BASE_VERSION: 1.0.0
  FULL_VERSION:
    ref: BASE_VERSION

映射变量 (map) ​

yaml
vars:
  CON极G:
    map:
      database:
        host: localhost
        port: 5432
      cache:
        type: redis
        ttl: 3600

变量排序 ​

变量可以引用先前定义的变量：

yaml
vars:
  GREETING: Hello
  TARGET: World
  MESSAGE: '{{.GREETING}} {{.TARGET}}!'

任务 (Task) ​

具有多种语法选项的单个任务配置。

简单任务格式 ​

yaml
tasks:
  # 字符串命令
  hello: echo "Hello World"

  # 命令数组
  build:
    - go mod tidy
    - go build ./...

  # 带有 cmd 简写的对象
  test:
    cmd: go test ./...

任务属性 ​

cmds ​

  • 类型: []Command
  • 描述: 要执行的命令
yaml
tasks:
  build:
极   cmds:
  - go build ./...
  - echo "Build complete"

cmd ​

  • 类型: string
  • 描述: 单个命令（cmds 的替代项）
yaml
tasks:
  test:
    cmd: go test ./...

deps ​

  • 类型: []Dependency
  • 描述: 在此任务之前运行的任务
yaml
tasks:
  # 简单依赖
  deploy:
    deps: [build, test]
    cmds:
      - ./deploy.sh

  # 带变量的依赖
  advanced-deploy:
    deps:
      - task: build
        vars:
          ENVIRONMENT: production
      - task: test
        vars:
          COVERAGE: true
    cmds: 极 ./deploy.sh

  # 静默依赖
  main:
    deps:
      - task: setup
        silent: true
    cmds:
      - echo "Main task"

  # 循环依赖
  test-all:
    deps:
      - for: [unit, integration, e2e]
        task: test
        vars:
          TEST_TYPE: '{{.ITEM}}'
    cmds:
      - echo "All tests completed"

desc ​

  • 类型: string
  • 描述: 在 --list 中显示的简短描述
yaml
tasks:
  test:
    desc: 运行单元测试
    cmds:
      - go test ./...

summary ​

  • 类型: string
  • 描述: 在 --summary 中显示的详细描述
yaml
tasks:
  deploy:
    desc: 部署到生产环境
    summary: |
      将应用程序部署到生产环境。
      这包括构建、测试和上传工件。

prompt ​

  • 类型: string 或 []string
  • 描述: 任务执行前显示的提示
yaml
tasks:
  deploy:
    prompt: "部署到生产环境?"
    # 或多个提示
    prompt:
      - "确定吗?"
      - "这将影响线上用户!"

aliases ​

  • 类型: []string
  • 描述: 任务的替代名称
yaml
tasks:
  build:
    aliases: [compile, make]
    cmds:
      - go build ./...

sources ​

  • 类型: []string 或 []Glob
  • 描述: 要监听更改的源文件
yaml
tasks:
  build:
    sources:
      - '**/*.go'
      - go.mod
      # 带排除项
      - exclude: '**/*_test.go'
    cmds:
      - go build ./...

generates ​

  • 类型: []string 或 []Glob
  • 描述: 此任务生成的文件
yaml
tasks:
  build:
    sources: ['**/*.go']
    generates:
      - './app'
      - exclude: '*.debug'
    cmds:
      - go build -o app ./cmd

status ​

  • 类型: []string
  • 描述: 检查任务是否应运行的命令
yaml
tasks:
  install-deps:
    status:
      - test -f node_modules/.installed
    cmds:
      - npm install
      - touch node_modules/.installed

preconditions ​

  • 类型: []Precondition
  • 描述: 运行前必须满足的条件
yaml
tasks:
  # 简单前置条件（简写）
  build:
    preconditions:
      - test -f ./src
    cmds:
      - go build ./...

  # 带有自定义消息的前置条件
  deploy:
    preconditions:
      - sh: test -n "$API_KEY"
        msg: '需要 API_KEY 环境变量'
      - sh: test -f ./app
        msg: "未找到应用二进制文件，请先运行 'task build'"
    cmds:
      - ./deploy.sh

requires ​

  • 类型: Requires
  • 描述: 必需变量，可带有可选枚举
yaml
tasks:
  # 简单要求
  deploy:
    requires:
      vars: [API_KEY, ENVIRONMENT]
    cmds:
      - ./deploy.sh

  # 带枚举验证的要求
  advanced-deploy:
    requires:
      vars:
        - API_KEY
        - name: ENVIRONMENT
          enum: [development, staging, production]
        - name: LOG_LEVEL
          enum: [debug, info, warn, error]
    cmds:
      - echo "部署到 {{.ENVIRONMENT}}，日志级别 {{.LOG_LEVEL}}"
      - ./deploy.sh

watch ​

  • 类型: bool
  • 默认值: false
  • 描述: 在监视模式下自动运行任务
yaml
tasks:
  dev:
    watch: true
    cmds:
      - npm run dev

platforms ​

  • 类型: []string
  • 描述: 应运行此任务的平台
yaml
tasks:
  windows-build:
    platforms: [windows]
    cmds:
      - go build -o app.exe ./cmd

  unix-build:
    platforms: [linux, darwin]
    cm极s:
      - go build -o app ./cmd

命令 (Command) ​

任务内的单个命令配置。

基本命令 ​

yaml
tasks:
  example:
    cmds:
      - echo "简单命令"
      - ls -la

命令对象 ​

yaml
tasks:
  example:
    cmds:
      - cmd: echo "Hello World"
        silent: true
        ignore_error: false
        platforms: [linux, darwin]
        set: [errexit]
        shopt: [globstar]

任务引用 ​

yaml
tasks:
  example:
    cmds:
      - task: other-task
        vars:
          PARAM: value
        silent: false

延迟命令 ​

yaml
tasks:
  with-cleanup:
    cmds:
      - echo "开始工作"
      # 延迟命令字符串
      - defer: echo "清理中"
      # 延迟任务引用
      - defer:
          task: cleanup-task
          vars:
            CLEANUP_MODE: full

For 循环 ​

循环遍历列表 ​

yaml
tasks:
  greet-all:
    cmds:
      - for: [alice, bob, charlie]
        cmd: echo "Hello {{.ITEM}}"

循环遍历 Sources/Generates ​

yaml
tasks:
  process-files:
    sources: ['*.txt']
    cmds:
      - for: sources
        cmd: wc -l {{.ITEM}}
      - for: generates
        cmd: gzip {{.ITEM}}

循环遍历变量 ​

yaml
tasks:
  process-items:
    vars:
      ITEMS: 'item1,item2,item3'
    cmds:
      - for:
          var: ITEMS
          split: ','
          as: CURRENT
        cmd: echo "Processing {{.CURRENT}}"

循环遍历矩阵 ​

yaml
tasks:
  test-matrix:
    cmds:
      - for:
          matrix:
            OS: [linux, windows, darwin]
            ARCH: [amd64, arm64]
        cmd: echo "Testing {{.OS}}/{{.ARCH}}"

依赖中的循环 ​

yaml
tasks:
  build-all:
    deps:
      - for: [frontend, backend, worker]
        task: build
        vars:
          SERVICE: '{{.ITEM}}'

Shell 选项 ​

Set 选项 ​

用于 POSIX shell 功能的可用 set 选项：

  • allexport / a - 导出所有变量
  • errexit / e - 出错时退出
  • noexec / n - 读取命令但不执行
  • noglob / 极 - 禁用路径名展开
  • nounset / u - 未定义变量时报错
  • xtrace / x - 执行前打印命令
  • pipefail - 管道失败传播
yaml
# 全局级别
set: [errexit, nounset, pipefail]

tasks:
  debug:
    # 任务级别
极   set: [xtrace]
    cmds:
      - cmd: echo "This will be traced"
        # 命令级别
        set: [noexec]

Shopt 选项 ​

用于 Bash 功能的可用 shopt 选项：

  • expand_aliases - 启用别名展开
  • globstar - 启用 ** 递归通配
  • nullglob - 空通配展开
yaml
# 全局级别
shopt: [globstar]

tasks:
  find-files:
    # 任务级别
    shopt: [nullglob]
    cmds:
      - cmd: ls **/*.go
        # 命令级别
        shopt: [globstar]