<p>PowerShell支持在脚本或函数正上方用<# #>注释块添加基于注释的帮助，需包含.SYNOPSIS（必填）、.DESCRIPTION、.PARAMETER等关键字，且注释必须为文件首个有效语句。</p>
powershell 支持通过特殊格式的注释块（称为“基于注释的帮助”或 comment-based help）为脚本、函数和模块提供内置帮助文档。这种帮助能被 get-help 命令识别并显示，无需额外生成外部文件。
Help 注释的基本位置和结构
Help 注释必须紧贴在脚本或函数定义的**正上方**，且中间不能有空行；如果是脚本，通常放在文件开头（但需确保前面没有可执行代码）。注释以 <# 开始、#> 结束，内部使用特定关键字标记内容：
- .SYNOPSIS：一句话概括功能（必填）
- .DESCRIPTION：详细说明用途、原理或使用场景
- .PARAMETER <Name>：描述每个参数（名称需与实际参数一致）
- .EXAMPLE：给出调用示例（可多个，每个以 .EXAMPLE 开头）
- .INPUTS 和 .OUTPUTS：说明支持的输入类型和返回值类型
- .NOTES：补充信息，如作者、版本、警告等
脚本级 Help 注释的写法示例
以下是一个完整脚本（如 Deploy-App.ps1）顶部的帮助注释：
<#
.SYNOPSIS
部署指定应用程序到目标服务器
.DESCRIPTION
该脚本通过 WinRM 连接远程服务器，复制安装包并执行静默安装。
支持日志记录和失败重试机制。
.PARAMETER ServerName
必需。目标服务器的主机名或 IP 地址。
.PARAMETER PackagePath
必需。本地安装包的完整路径（如 C:\Temp\AppSetup.msi）。
.PARAMETER RetryCount
可选。安装失败时重试次数，默认为 2。
.EXAMPLE
.\Deploy-App.ps1 -ServerName "SRV01" -PackagePath "C:\Apps\MyApp.msi"
.EXAMPLE
.\Deploy-App.ps1 -ServerName "SRV02" -PackagePath "D:\Inst\setup.exe" -RetryCount 3
.INPUTS
None
.OUTPUTS
System.Boolean：成功返回 $true，失败返回 $false
.NOTES
Author: admin
Version: 1.2
Updated: 2024-05-20
#>
保存后，在同一目录下运行 Get-Help .\Deploy-App.ps1 即可看到格式化帮助。
关键注意事项
- 注释块必须是脚本中第一个有效语句（前面只能有空白行或纯注释）
- 每个关键字（如
.PARAMETER）必须独占一行，且顶格书写（前面不能有空格） - 参数名要与函数/脚本中
param()定义的名称完全一致（包括大小写） - 若脚本含多个函数，建议只为导出的主函数添加顶层 Help；内部辅助函数的帮助应放在其 function 块正上方
- 运行
Get-Help script.ps1 -Full查看全部字段；首次使用可能需先执行Update-Help（仅对模块必要，脚本无需）
验证和调试技巧
如果 Get-Help 不显示你的帮助，请检查：
- 是否误将注释写在
param()或begin{}后面 - 是否有隐藏字符（如 BOM）或编码问题（推荐保存为 UTF-8 无 BOM）
- 是否在脚本中调用了
Set-Alias或其他命令干扰了解析（避免在 Help 前放任何可执行语句） - 使用
Get-Help script.ps1 -ShowWindow在图形窗口中查看排版效果
