命令行与文本处理 / 系统课时
使用 PSScriptAnalyzer
使用 PSScriptAnalyzer
本课把 PSScriptAnalyzer 接入一个最小 PowerShell 项目:先安装并运行内置规则,再用设置文件统一严重级别和命名要求,最后编写一条自定义规则。完成后,你可以在本地和持续集成中使用同一套检查标准。
学习目标
- 安装 PSScriptAnalyzer 并读取结构化诊断结果
- 使用
PSScriptAnalyzerSettings.psd1固化项目规则 - 编写、加载并验证一条 PowerShell 自定义分析规则
安装并确认模块
PSScriptAnalyzer 会分析 .ps1、.psm1 和 .psd1 文件,并返回包含规则名、严重级别、行号和消息的诊断对象;Get-ScriptAnalyzerRule 可用于查看当前可用规则。:contentReference[oaicite:3]{index=3}
以下命令需要能够访问 PowerShell Gallery。已经安装模块时不会重复安装。
$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预期输出
Name Version
---- -------
PSScriptAnalyzer <VERSION><VERSION> 取决于当前安装版本。若安装阶段提示仓库不受信任,应先确认仓库地址与组织策略,不要在来源不明的环境中直接放宽信任设置。
用设置文件统一检查标准
设置文件适合提交到版本库,让开发机、编辑器和 CI 使用同一套规则。下面创建一个有意包含问题的脚本,并只启用两个警告规则。
$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预期输出
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 目录中创建规则模块,再分析前面的示例脚本。
$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预期输出
RuleName Severity Line Message
-------- -------- ---- -------
Measure-CompanyFunctionName Warning 1 函数 'Fetch-UserInfo' 不符合公司命名规范自定义规则应只表达组织特有且可验证的约束。若规则过于主观,会产生大量误报,最终导致团队忽略真正重要的警告。
接入项目质量门禁
本地开发可先输出完整诊断对象,CI 中再按严重级别决定是否失败。Invoke-ScriptAnalyzer -EnableExit 会用错误记录数量作为退出码,适合把错误级问题设为阻断条件;警告是否阻断应由团队明确约定。:contentReference[oaicite:6]{index=6}
不要直接对整个代码库使用 -Fix。自动修复只适用于支持修复的规则,并且可能改变格式或代码;正确做法是先在独立分支运行、查看差异、执行测试,再决定是否提交。