命令行与文本处理 / 系统课时

适配跨平台命令

适配跨平台命令

本课把平台差异收敛到一个小型适配层:先识别 Windows、Linux 或 macOS,再选择对应的原生命令与参数,并通过统一执行器捕获标准输出、标准错误和退出码,避免字符串拼接带来的转义与注入问题。

学习目标

  • 使用 PowerShell 7 的平台变量选择正确的命令分支
  • 以参数数组安全调用原生程序,并分别捕获两个输出流
  • 依据退出码判定成功,设计可维护的平台差异边界

先识别平台与能力

PowerShell 7 提供 $IsWindows、$IsLinux 和 $IsMacOS。平台判断用于选择确实不同的命令或参数;执行前仍应使用 Get-Command 检查程序是否存在,因为同一平台的精简系统、容器或服务器镜像也可能缺少某个工具。

跨平台原生命令适配流程

不要仅凭路径格式推断平台,也不要假设命令名称相同就意味着参数兼容。例如 ping 在 Windows 使用 -n 指定次数,而 Linux 和 macOS 通常使用 -c。

安全调用原生命令

下面的完整脚本以 PowerShell 7 为运行环境。统一执行器使用 ProcessStartInfo.ArgumentList 逐项传递参数,不经过额外的命令行字符串解析;同时异步读取标准输出和标准错误,避免大量输出时互相阻塞。

powershell
Set-StrictMode -Version Latest
$ErrorActionPreference = 'Stop'

if ($PSVersionTable.PSVersion.Major -lt 7) {
    throw '本示例需要 PowerShell 7 或更高版本。'
}

function Invoke-NativeChecked {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory)]
        [string] $FilePath,

        [string[]] $ArgumentList = @(),

        [int[]] $AllowedExitCode = @(0)
    )

    $command = Get-Command `
        -Name $FilePath `
        -CommandType Application `
        -ErrorAction Stop |
        Select-Object -First 1

    # 使用参数列表而不是拼接整条命令,保留每个参数的边界。
    $startInfo = [Diagnostics.ProcessStartInfo]::new()
    $startInfo.FileName = $command.Source
    $startInfo.UseShellExecute = $false
    $startInfo.RedirectStandardOutput = $true
    $startInfo.RedirectStandardError = $true
    $startInfo.CreateNoWindow = $true

    foreach ($argument in $ArgumentList) {
        [void] $startInfo.ArgumentList.Add($argument)
    }

    $process = [Diagnostics.Process]::new()
    $process.StartInfo = $startInfo

    if (-not $process.Start()) {
        throw "无法启动原生命令:$($command.Source)"
    }

    # 同时读取两个流,避免一侧缓冲区写满导致进程等待。
    $stdoutTask = $process.StandardOutput.ReadToEndAsync()
    $stderrTask = $process.StandardError.ReadToEndAsync()
    $process.WaitForExit()

    $stdout = $stdoutTask.GetAwaiter().GetResult().TrimEnd()
    $stderr = $stderrTask.GetAwaiter().GetResult().TrimEnd()
    $exitCode = $process.ExitCode
    $process.Dispose()

    if ($AllowedExitCode -notcontains $exitCode) {
        $detail = if ($stderr) { $stderr } else { $stdout }
        throw "原生命令失败,退出码 $exitCode:$detail"
    }

    [pscustomobject]@{
        FilePath       = $command.Source
        Arguments      = $ArgumentList
        ExitCode       = $exitCode
        StandardOutput = $stdout
        StandardError  = $stderr
    }
}

# 平台分支只保存差异,调用、检查与错误处理保持一致。
if ($IsWindows) {
    $platform = 'Windows'
    $nativeCommand = 'ping.exe'
    $nativeArgs = @('-n', '1', '127.0.0.1')
}
elseif ($IsLinux) {
    $platform = 'Linux'
    $nativeCommand = 'ping'
    $nativeArgs = @('-c', '1', '127.0.0.1')
}
elseif ($IsMacOS) {
    $platform = 'macOS'
    $nativeCommand = 'ping'
    $nativeArgs = @('-c', '1', '127.0.0.1')
}
else {
    throw '当前平台不在支持范围内。'
}

$result = Invoke-NativeChecked `
    -FilePath $nativeCommand `
    -ArgumentList $nativeArgs

[pscustomobject]@{
    Platform       = $platform
    Command        = $result.FilePath
    ExitCode       = $result.ExitCode
    StdOutCaptured = -not [string]::IsNullOrWhiteSpace(
        $result.StandardOutput
    )
    StdErrCaptured = -not [string]::IsNullOrWhiteSpace(
        $result.StandardError
    )
}

预期输出如下,命令绝对路径和平台名称以实际环境为准:

text
Platform       : <PLATFORM>
Command        : <PATH>
ExitCode       : 0
StdOutCaptured : True
StdErrCaptured : False

若系统未安装 ping,脚本会在能力检查阶段抛出“无法将命令识别为应用程序”一类错误,而不是继续执行一个错误的平台分支。此时应安装对应系统工具,或把分支改成环境中确定存在的命令。

正确处理参数与退出码

参数应始终作为数组保存,每个数组元素对应原生程序接收的一个参数。不要将用户输入拼接成 "tool $value" 后交给 Invoke-Expression、cmd /c 或 sh -c;这些方式会引入第二层解析,空格、引号和控制字符都可能改变命令含义。

使用调用运算符 & $command @arguments 也能安全保留参数边界,适合输出量较小、无需分离两个流的简单调用。调用结束后应立即复制 $LASTEXITCODE,因为后续原生命令会覆盖它;$? 只能快速表示上一条命令是否成功,精确诊断仍应记录退出码。

标准错误不等于“PowerShell 异常”。原生程序通常把诊断文本写入 stderr,并通过非零退出码表示失败。统一执行器应同时保存 stderr 和 stdout;有些程序会把普通进度写入 stderr,因此最终成功判定应以该工具约定的退出码为主。

把差异限制在适配层

可维护的跨平台脚本应把“变化项”和“共同行为”分开。平台分支只决定命令名称、参数、默认路径或功能开关;日志、超时、输出解析、退出码校验和异常格式由统一函数处理。新增平台时只扩展差异数据,不复制整个执行流程。

优先做能力检测,再做平台检测。若多个平台都安装同一个兼容工具,直接使用 Get-Command 找到它即可;只有命令语义或参数确实不同时才分支。这样可以兼容容器、WSL、最小化镜像和用户自行安装的工具。

调用外部程序时还要固定区域无关的输出格式,或尽量使用机器可读选项,例如 JSON。直接解析本地化的人类文本容易因系统语言、工具版本或空格变化而失效。

常见失败与验证顺序

遇到“本机成功、换平台失败”时,先输出平台与 PowerShell 版本,再检查命令是否存在和最终参数数组。随后单独运行原生命令,确认退出码与 stderr,最后才检查业务解析逻辑。

路径问题应使用 Join-Path、$PSScriptRoot 和平台提供的目录变量解决,不要手写混合分隔符。权限问题则应检查目标文件执行权限、当前账户和工作目录;不要通过整体提升为管理员或 root 来掩盖最小权限配置错误。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

适配跨平台命令

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通