PowerShell 没有“返回数组”这回事
上周同事的脚本在测试环境跑了两周都没问题,上线第一天却失败了。测试库里有几十条记录,生产库那天只有一条。代码没有改,变量却从数组变成了字符串。
这类 bug 在 PowerShell 里很常见,因为 PowerShell 的函数并不“返回”值:它往流里写东西,而调用方拿到的,是这条流被收集之后的结果。
函数写的是流
1function Get-Name {
2 'alice'
3 'bob'
4}
5
6$r = Get-Name
7$r.GetType().Name # Object[]
8$r.Count # 2函数体里每一个没有被消费掉的对象,都会按顺序进入成功流。return 并不特殊,它只是“把后面的对象写进流,然后结束函数”。
调用方拿到什么,只取决于流里有几个对象:
| 流里的对象数 | $r 是什么 |
|---|---|
| 0 | $null |
| 1 | 那个对象本身 |
| n | Object[] |
所以严格说,PowerShell 里没有“返回一个数组”这个动作,只有“往流里写了 n 个东西,恰好被收集成数组”。
只剩一条时,类型就变了
最典型的场景是读日志:
1function Get-ErrorLine {
2 param([string]$Path)
3 Get-Content $Path | Where-Object { $_ -match 'ERROR' }
4}
5
6$lines = Get-ErrorLine ./app.logGet-Content 读到多行时是 string[],读到单行文件时是一个 string。于是同一个函数,输出三条错误时返回 Object[],输出一条错误时返回 String。接着:
1$lines[0] # 三条时是第一行;一条时是这一行的第一个字符
2$lines.Length # 三条时是行数;一条时是字符数.Count 是最容易让人误判的。从 PowerShell 3.0 起,标量也被补上了 Count 属性,$lines.Count 在两种情况下都能正常返回 1 或 3,看起来没有问题。测试数据多的时候一切正常;线上只有一条时,[0] 和 .Length 已经悄悄换了含义。
零条记录时更隐蔽:
1$lines = Get-ErrorLine ./empty.log # $null
2$lines.Count # 0,看起来正常
3$lines[0] # $null
4$lines.ToString() # 空引用异常$null 和执行“返回了一个空数组”是两件事,很多下游逻辑区分不出来。
管道默认会展开集合
数组进入管道时会被拆成一个个元素:
1@(1, 2, 3) | ForEach-Object { "item: $_" } # 三行
2,@(1, 2, 3) | ForEach-Object { "item: $_" } # 一行,$_ 是 1 2 3一元逗号 , 构造了一个“只含一个元素的数组”,这个元素才是原数组。管道展开的是外层,里层就保住了。
也不是所有东西都会被展开:
| 对象 | 进入管道后 |
|---|---|
| 数组、List、HashSet | 逐个元素 |
| 字符串 | 整体一个 |
| 哈希表 | 整体一个 |
| PSCustomObject | 整体一个 |
哈希表是 IDictionary,PowerShell 有意不拆它,否则 @{a=1} 会变成一堆 DictionaryEntry。
反过来:函数会偷偷多返回东西
流的另一个问题是它不挑来源。任何没有落到变量里、没有接 Out-Null 的输出,都会混进“返回值”:
1function Initialize-Workspace {
2 param([string]$Path)
3 New-Item -ItemType Directory -Path $Path -Force
4 Set-Location $Path
5 'ready'
6}
7
8$result = Initialize-Workspace ./out
9$result.GetType().Name # Object[],里面是 DirectoryInfo 和 String调用方以为拿到的是 'ready',其实是两个对象。if ($result) 永远为真,.Count 永远是 2。
方法的返回值也一样:
1$sb = [System.Text.StringBuilder]::new()
2$sb.Append('a') # 输出的是 StringBuilder 本身
3[void]$sb.Append('a') # 丢弃
4$null = $sb.Append('a') # 同样丢弃
5
6$list = [System.Collections.ArrayList]::new()
7$list.Add('a') # 输出 0,也就是新元素的索引在循环里调 .Add(),屏幕上会莫名其妙冒出一串数字,原因就在这里。
把边界写明确
| 场景 | 写法 |
|---|---|
| 调用方不确定结果有几个 | $r = @(Get-Thing) |
| 函数要交出一个集合 | return ,$arr |
| 同上,用 cmdlet 语法 | Write-Output -NoEnumerate $arr |
| 高级函数里 | $PSCmdlet.WriteObject($arr, $false) |
| 调用只为副作用的方法 | [void]$obj.Method() |
| 参数必须收数组 | param([string[]]$Name) |
空数组的例子最能说明差别:
1function Get-None { return @() }
2function Get-None2 { return ,@() }
3
4$null -eq (Get-None) # True,什么都没写进流
5$null -eq (Get-None2) # False,(Get-None2).Count 是 0排查时先看类型
遇到“数据少的时候才出错”的脚本,第一步不是读逻辑,而是确认类型:
1$r.GetType().FullName
2@($r).Count
3$r | Measure-Object如果函数是你自己写的,就问一句:我是在往流里写东西,还是在交出一个值?前者适合管道,后者就该用 ,、-NoEnumerate 或者 WriteObject 把边界钉死。PowerShell 的灵活来自这条流,麻烦也来自这条流。
本文由 AI 辅助生成并经人工校验,如有疏漏欢迎指正。