GitHub Actions workflow_call 怎样给复用工作流定义类型化输入

把一段部署或测试流程抽成 GitHub Actions 复用工作流后，最容易出错的地方是：调用方传了值，被调用工作流却没有明确声明类型，最后只能靠字符串猜。更稳的做法是，在被调用工作流的 on.workflow_call.inputs 中声明输入，在调用方的 jobs..with 中传值，再在工作流内部用 inputs. 读取。

官方文档：https://docs.github.com/en/actions/how-tos/reuse-automations/reuse-workflows

核心记法是“被调用方定义 inputs，调用方用 with 传值，步骤内用 inputs 读取”。workflow_call 输入类型只能写 boolean、number 或 string，不要把它和手动触发工作流的输入写法混在一起。

先在复用工作流中定义输入契约

先打开仓库的 .github/workflows/reusable-check.yml。在 on.workflow_call.inputs 下，每个输入至少要有 type；是否必填由 required 控制。下面用环境名、并发数和是否执行检查三个字段，分别覆盖字符串、数字和布尔值。

name: Reusable check

on:
  workflow_call:
    inputs:
      environment:
        # 字符串适合传环境名、目录或短标签。
        required: true
        type: string
      parallelism:
        # number 用于需要参与数值判断的参数。
        required: false
        default: 2
        type: number
      run-check:
        # boolean 可以直接用于 if 条件，不必手动比较字符串。
        required: false
        default: true
        type: boolean

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - name: Print received inputs
        run: |
          # 先打印关键输入，便于在运行日志中核对调用方传值。
          echo "environment=${{ inputs.environment }}"
          echo "parallelism=${{ inputs.parallelism }}"
          echo "run-check=${{ inputs.run-check }}"
      - name: Run checks
        if: ${{ inputs.run-check }}
        run: |
          # 这里只示意消费参数，实际检查命令按项目替换。
          echo "run checks with parallelism=${{ inputs.parallelism }}"

这里有两个容易忽略的边界：没有写 default 时，布尔值默认是 false，数字默认是 0，字符串默认是空字符串；调用方传入一个被调用方没有声明的输入，会直接产生配置错误。

在调用方用 with 传入对应类型

回到调用方工作流，例如 .github/workflows/nightly.yml。复用工作流是一个 job 级调用，参数放在同一个 job 的 with 下，键名必须与上面的输入名完全一致。不要把它写成某个 step 的 with，那是 action 参数的另一套语法。

name: Nightly check

on:
  workflow_dispatch:

jobs:
  call-check:
    # 直接引用复用工作流文件，版本或分支按仓库策略固定。
    uses: ./.github/workflows/reusable-check.yml
    with:
      # string 直接传入环境标识。
      environment: staging
      # number 不要为了“看起来像数字”额外加引号。
      parallelism: 4
      # boolean 保持布尔写法，供被调用方的 if 使用。
      run-check: true

页面上可以进入 Actions → Nightly check → 运行记录 → Jobs 查看调用 job。先确认 job 成功进入被调用工作流，再看日志中打印出的三个字段；这一步能把“没有触发”与“触发了但参数不对”分开。

用 inputs 上下文核对实际生效值

参数声明成功后，真正的验收点不在 YAML 编辑器，而在一次运行的日志。被调用工作流中的任意 job 或 step 都可以访问 inputs 上下文。对于布尔值，直接放在 if 中最清楚；对于字符串和数字，可以在日志里输出后与调用方的 with 逐项比对。

建议按下面的顺序核对：

1. 调用 job 的 uses 是否指向预期的工作流文件。
2. with 下的键名是否与 workflow_call.inputs 一一对应。
3. 被调用工作流第一步日志中的值是否符合预期，尤其是 false、0 和空字符串。
4. 当 run-check: false 时，检查步骤是否显示为跳过，而不是把字符串 "false" 当成真值。

常见错误：输入名、类型和默认值不一致

如果运行前就提示输入不存在，先对比两份 YAML 的字段名；environment 和 env 不是同一个输入。如果配置能保存但条件结果不符合预期，再看调用方是否把布尔值写成了带引号的文本，以及被调用方是否依赖了未声明的默认值。

还要区分 workflow_call 与 workflow_dispatch：前者服务复用工作流，输入由调用 job 的 with 提供；后者服务手动运行，输入定义在手动触发器下。两者都能使用 inputs 上下文，但输入来源和类型声明位置不同。

相关问题

workflow_call 的 number 能传小数吗？

可以按数字类型传递；如果业务只接受整数，仍应在工作流步骤中做范围或整数判断，不能只依赖输入声明。

为什么调用方传了一个新字段就报错？

调用方只能传被调用工作流已经在 workflow_call.inputs 中声明的字段。先补声明并写明 type，再重新运行。