GitHub Actions动态生成矩阵：单条目JSON失效求通用方案

问题根源 #

当从数据库获取单条数据时，PowerShell默认输出的JSON是单个对象而非数组，导致GitHub Actions的fromJSON无法正确解析为矩阵所需的数组结构，进而创建单作业矩阵失败。

通用解决方法 #

1. 强制包装为数组（兼容所有PowerShell版本）

无论获取到的数据是单条还是多条，都用@()语法强制包装成数组，确保JSON输出始终是数组结构：

# 模拟从数据库获取数据（替换为实际数据库查询逻辑）
$dbData = Get-DatabaseRecords

# 强制将数据转为数组
$matrixItems = @($dbData)

# 输出符合GitHub Actions要求的矩阵JSON
Write-Output "matrix=$(ConvertTo-Json -InputObject @{ include = $matrixItems } -Compress)" >> $env:GITHUB_OUTPUT

@($dbData)会自动处理两种场景：单条数据转为单元素数组，多条数据保留原有数组结构。

2. 显式类型判断（可选）

如果需要更明确的逻辑，可以先判断数据类型再处理：

$dbData = Get-DatabaseRecords

if ($dbData -isnot [array]) {
    $matrixItems = @($dbData)
} else {
    $matrixItems = $dbData
}

Write-Output "matrix=$(ConvertTo-Json -InputObject @{ include = $matrixItems } -Compress)" >> $env:GITHUB_OUTPUT

3. 使用PowerShell 7+的-AsArray参数

若你的工作流使用PowerShell 7及以上版本，可直接用ConvertTo-Json的-AsArray参数强制输出数组：

$dbData = Get-DatabaseRecords

# -AsArray强制将输入转为数组结构
$jsonOutput = ConvertTo-Json -InputObject @{ include = $dbData } -Compress -AsArray
Write-Output "matrix=$jsonOutput" >> $env:GITHUB_OUTPUT

注意事项 #

• 矩阵JSON必须包含include字段（结构为{ "include": [ ... ] }），这是GitHub Actions矩阵的标准格式
• 使用-Compress参数压缩JSON，避免换行符导致的解析异常
• 新版GitHub Actions推荐使用GITHUB_OUTPUT环境变量传递输出，替代旧版的::set-output命令

内容的提问来源于stack exchange，提问作者Ashar