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

使用 PSScriptAnalyzer

使用 PSScriptAnalyzer

本课把 PSScriptAnalyzer 接入一个最小 PowerShell 项目:先安装并运行内置规则,再用设置文件统一严重级别和命名要求,最后编写一条自定义规则。完成后,你可以在本地和持续集成中使用同一套检查标准。

学习目标

  • 安装 PSScriptAnalyzer 并读取结构化诊断结果
  • 使用 PSScriptAnalyzerSettings.psd1 固化项目规则
  • 编写、加载并验证一条 PowerShell 自定义分析规则

安装并确认模块

PSScriptAnalyzer 会分析 .ps1、.psm1 和 .psd1 文件,并返回包含规则名、严重级别、行号和消息的诊断对象;Get-ScriptAnalyzerRule 可用于查看当前可用规则。:contentReference[oaicite:3]{index=3}

以下命令需要能够访问 PowerShell Gallery。已经安装模块时不会重复安装。

powershell
$ErrorActionPreference = 'Stop'

if (-not (Get-Module -ListAvailable -Name PSScriptAnalyzer)) {
    Install-Module -Name PSScriptAnalyzer -Scope CurrentUser -Force
}

Import-Module PSScriptAnalyzer
Get-Module PSScriptAnalyzer |
    Select-Object Name, Version

预期输出

text
Name             Version
----             -------
PSScriptAnalyzer <VERSION>

<VERSION> 取决于当前安装版本。若安装阶段提示仓库不受信任,应先确认仓库地址与组织策略,不要在来源不明的环境中直接放宽信任设置。

用设置文件统一检查标准

设置文件适合提交到版本库,让开发机、编辑器和 CI 使用同一套规则。下面创建一个有意包含问题的脚本,并只启用两个警告规则。

powershell
$projectPath = Join-Path $PWD 'analyzer-demo'
New-Item -ItemType Directory -Path $projectPath -Force | Out-Null

@'
function Fetch-UserInfo {
    [CmdletBinding()]
    param([string]$Name)

    Write-Host "Loading $Name"
}

Fetch-UserInfo -Name 'demo'
'@ | Set-Content -Path (Join-Path $projectPath 'Demo.ps1') -Encoding utf8

@'
@{
    Severity     = @('Error', 'Warning')
    IncludeRules = @(
        'PSUseApprovedVerbs'
        'PSAvoidUsingWriteHost'
    )
}
'@ | Set-Content -Path (Join-Path $projectPath 'PSScriptAnalyzerSettings.psd1') -Encoding utf8

Invoke-ScriptAnalyzer `
    -Path (Join-Path $projectPath 'Demo.ps1') `
    -Settings (Join-Path $projectPath 'PSScriptAnalyzerSettings.psd1') |
    Select-Object RuleName, Severity, Line, Message |
    Format-Table -AutoSize

预期输出

text
RuleName                  Severity Line Message
--------                  -------- ---- -------
PSUseApprovedVerbs        Warning     1 <MESSAGE>
PSAvoidUsingWriteHost     Warning     5 <MESSAGE>

<MESSAGE> 的具体措辞可能随模块版本变化。第一条说明 Fetch 不是批准动词,第二条提示库代码通常不应依赖 Write-Host。修复时可把函数改为 Get-UserInfo,并把输出改为 Write-Output、详细流或信息流。

-IncludeRule 只运行选中的规则,-ExcludeRule 排除指定规则,-Severity 过滤严重级别;项目设置可通过 -Settings 显式加载。自定义规则路径默认只运行自定义规则,需要同时启用内置规则时再加 -IncludeDefaultRules。:contentReference[oaicite:4]{index=4}

编写一条自定义规则

组织规则无法被内置规则覆盖时,可以创建 PowerShell 模块。规则函数需要接收名称以 Ast 结尾的 AST 参数,返回 DiagnosticRecord,并通过 Export-ModuleMember 导出。:contentReference[oaicite:5]{index=5}

下面的规则要求函数名以 Get-Corp、Set-Corp、New-Corp 或 Remove-Corp 开头。先在 analyzer-demo 目录中创建规则模块,再分析前面的示例脚本。

powershell
$rulePath = Join-Path $projectPath 'CompanyRules.psm1'

@'
function Measure-CompanyFunctionName {
    [CmdletBinding()]
    [OutputType([Microsoft.Windows.PowerShell.ScriptAnalyzer.Generic.DiagnosticRecord[]])]
    param(
        [Parameter(Mandatory)]
        [ValidateNotNullOrEmpty()]
        [System.Management.Automation.Language.ScriptBlockAst]$ScriptBlockAst
    )

    $functions = $ScriptBlockAst.FindAll({
        param($Ast)
        $Ast -is [System.Management.Automation.Language.FunctionDefinitionAst]
    }, $true)

    foreach ($function in $functions) {
        if ($function.Name -notmatch '^(Get|Set|New|Remove)-Corp') {
            [Microsoft.Windows.PowerShell.ScriptAnalyzer.Generic.DiagnosticRecord]@{
                Message  = "函数 '$($function.Name)' 不符合公司命名规范"
                Extent   = $function.Extent
                RuleName = $PSCmdlet.MyInvocation.InvocationName
                Severity = 'Warning'
            }
        }
    }
}

Export-ModuleMember -Function Measure-CompanyFunctionName
'@ | Set-Content -Path $rulePath -Encoding utf8

Invoke-ScriptAnalyzer `
    -Path (Join-Path $projectPath 'Demo.ps1') `
    -CustomRulePath $rulePath |
    Select-Object RuleName, Severity, Line, Message |
    Format-Table -AutoSize

预期输出

text
RuleName                   Severity Line Message
--------                   -------- ---- -------
Measure-CompanyFunctionName Warning    1 函数 'Fetch-UserInfo' 不符合公司命名规范

自定义规则应只表达组织特有且可验证的约束。若规则过于主观,会产生大量误报,最终导致团队忽略真正重要的警告。

接入项目质量门禁

本地开发可先输出完整诊断对象,CI 中再按严重级别决定是否失败。Invoke-ScriptAnalyzer -EnableExit 会用错误记录数量作为退出码,适合把错误级问题设为阻断条件;警告是否阻断应由团队明确约定。:contentReference[oaicite:6]{index=6}

不要直接对整个代码库使用 -Fix。自动修复只适用于支持修复的规则,并且可能改变格式或代码;正确做法是先在独立分支运行、查看差异、执行测试,再决定是否提交。

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

目录与阅读设置

阅读设置

17

记录一个想法

使用 PSScriptAnalyzer

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

登录哪都通