官方文档也坑人？$ErrorActionPreference 行为与描述完全相反的真相

在 PowerShell 的自动化世界里，$ErrorActionPreference 是掌握脚本生杀大权的核心变量。如果你按照官方 FAQ 或早期的文档描述去配置它，你可能会陷入一个极其诡异的境地：明明设置了“静默继续”，脚本却依然在关键时刻卡住；或者你以为它会报错抛出异常，它却在数据损坏后选择了“装死”。

最近社区中一个高热度的 Issue #27350 揭开了这个皇帝的新衣：官方 docs/FAQ.md 中关于错误处理的描述，竟然与 pwsh 引擎的实际行为完全相反。这种“文档级”的陷阱，足以让最资深的运维架构师在深夜排错时怀疑人生。

💡 报错现象总结：开发者在 docs/FAQ.md 引导下设置 $ErrorActionPreference = 'Stop' 期望捕获非中止错误，结果脚本在某些特定 Cmdlet（如 Get-Item）遇到权限问题时，并未按照文档预期的逻辑进入 try-catch 块；或者在设置为 SilentlyContinue 后，某些关键的底层异常依然被强行推送到控制台。

---

文档 vs 现实：$ErrorActionPreference 的语义崩塌

在 Issue #27350 提交之前，官方文档中长期存在一种误导性的解释，认为某些偏好设置可以改变错误的“本质”。

架构逻辑：文档描述与引擎实现的“南辕北辙”

官方 FAQ (错误描述)	引擎实际行为 (Issue #27350 修正后)	架构师视角结论
Stop	会将所有警告和信息也转为报错	仅将“非中止错误”升级为“中止错误”
Continue	报错后立即停止当前管道	显示错误并继续执行下一行/下一项
SilentlyContinue	彻底销毁错误对象以节省内存	仅压制控制台输出，$Error 变量仍会记录
Inquire	只有在发生致命错误时才弹窗	对每一个非中止错误都会暂停并询问

在源码层面，PowerShell 引擎在处理 Cmdlet 抛出的 WriteError 方法时，会首先检查这个全局变量。问题在于，文档在解释“非中止错误”（Non-terminating Error）如何转化为“中止错误”（Terminating Error）时，逻辑出现了致命的倒置。这导致很多开发者在编写高可用脚本时，错误地估计了 try-catch 的生效范围。

---

填坑实战：被文档误导后的“捕获失败”惨剧

假设你正在编写一个自动清理临时文件的脚本，你希望一旦某个文件无法访问，脚本就立即停止并报警。按照官方 FAQ 的逻辑，你会这么写：

# 这种基于错误文档编写的代码，在生产环境下极其危险
$ErrorActionPreference = 'Stop'

try {
    # 假设这里的目录不存在或权限不足
    Get-ChildItem -Path "C:\Sensitive\Data" -Recurse
}
catch {
    Write-Host "捕获到异常，发送报警邮件..."
}
# 痛点：在旧版逻辑或某些特殊 Cmdlet 下，
# 文档描述的‘Stop’并不能 100% 保证触发 catch 块，
# 导致脚本在错误发生后继续执行了后面的“高危清理”指令。

为什么这种“官方推荐”写法会坑人？

1. 作用域黑盒：某些二进制模块编写时没有遵循 PS 的标准偏好协议，导致全局变量失效。
2. 错误流混淆：文档没有说清楚 $ErrorActionPreference 对 $_（当前错误对象）生命周期的影响，导致你在 catch 块里拿到的错误信息可能是空的。
3. 参数优先级：很多人不知道 Cmdlet 级别的 -ErrorAction 参数会完全覆盖全局变量，导致代码审查时出现视觉盲点。

---

终极解药：PS 官方文档错误订正集

与其在错误的文档里打转，不如直接查看经过社区硬核校验的“真相”。

为了帮大家规避这些官方留下的“雷区”，我已经在 GitCode 上整理并实时更新 《PS 官方文档错误订正集》。这份资料不仅仅是翻译纠错，更包含了针对 Issue #27350 的深度行为测试报告。

订正集核心内容：

• $ErrorActionPreference 行为矩阵：覆盖所有可选值的 20 种真实业务场景实测结果。
• 异常捕获最佳实践：教你如何组合使用 Try-Catch 与 -ErrorAction，实现真正的“零漏报”监控。
• 社区高票 Issue 避坑指南：汇总了类似 #27350 这种“文档与代码不符”的隐蔽陷阱。

技术老炮的经验不是看文档看出来的，而是踩坑踩出来的。[点击前往 GitCode 查阅《PS 官方文档错误订正集》]，注册即取。别让官方的笔误，成了你系统宕机的导火索。