windows-shell-reliability

Windows Shell 可靠性模式

通过 PowerShell 和 CMD 在 Windows 上运行命令的最佳实践。

适用场景

在开发或调试运行于 Windows 系统上的脚本和自动化任务时，尤其是涉及文件路径、字符编码或标准 CLI 工具时，使用此技能。

---

1. 编码与重定向

重要：不同 PowerShell 版本的重定向差异

较旧版本的 Windows PowerShell 可能会以某些方式重写原生命令的输出，导致后续处理失败。PowerShell 7.4+ 在重定向标准输出时会保留字节流，因此只有在使用较旧的 Shell 行为或日志文件已无法读取时，才应用 UTF-8 转换变通方案。

问题	表现	解决方案
dotnet > log.txt	在较旧的 Windows PowerShell 中，view_file 失败	`Get-Content log.txt
npm run > log.txt	需要包含错误信息的 UTF-8 文本日志	`npm run ... 2>&1

规则： 在 PowerShell 7.4+ 中优先直接使用原生重定向；只有在较旧的 Windows PowerShell 重定向生成无法读取的日志时，才显式转换为 UTF-8。

---

2. 处理路径与空格

重要：加引号

Windows 路径通常包含空格。

❌ 错误	✅ 正确
dotnet build src/my project/file.fsproj	dotnet build "src/my project/file.fsproj"
& C:\Path With Spaces\bin.exe	& "C:\Path With Spaces\bin.exe"

规则： 绝对路径和相对路径可能包含空格时，始终为其加上引号。

调用运算符 (&)

在 PowerShell 中，如果可执行文件路径以引号开头，必须使用 & 运算符。

模式：

& "C:\Program Files\dotnet\dotnet.exe" build ...

---

3. 常见二进制文件与 Cmdlet 陷阱

操作	❌ CMD 风格	✅ PowerShell 选项
删除	del /f /q file	Remove-Item -Force file
复制	copy a b	Copy-Item a b
移动	move a b	Move-Item a b
创建目录	mkdir folder	New-Item -ItemType Directory -Path folder

提示： 在 PowerShell 中使用 ls、cat 和 cp 等 CLI 别名通常没有问题，但在脚本中使用完整的 Cmdlet 更可靠。

---

4. Dotnet CLI 可靠性

构建速度与一致性

场景	命令	原因
快速迭代	dotnet build --no-restore	跳过冗余的 nuget 还原。
清理构建	dotnet build --no-incremental	禁用增量编译；怀疑存在过期输出时，使用单独的清理步骤。
后台运行	Start-Process dotnet -ArgumentList 'run' -RedirectStandardOutput output.txt -RedirectStandardError error.txt	在不阻塞 Shell 的情况下启动应用，并保留日志。

---

5. 环境变量

Shell	语法
PowerShell	$env:VARIABLE_NAME
CMD	%VARIABLE_NAME%

---

6. 长路径

Windows 默认的路径长度限制为 260 个字符。

解决方法： 遇到长路径错误时，使用扩展路径前缀： \\?\C:\Very\Long\Path\...

---

7. 排查 Shell 错误

错误	可能原因	修复方法
The term 'xxx' is not recognized	路径不在 $env:PATH 中	使用绝对路径或修正 PATH。
Access to the path is denied	文件正在使用或权限不足	检查所有权和锁定状态；仅停止已获授权的进程，并避免将提权作为默认修复方式。
Encoding mismatch	较旧 Shell 的重定向重写了输出	将文件重新导出为 UTF-8，或使用 `2>&1

---

限制

• 仅当任务明确符合上述范围时，才使用此技能。
• 不要将输出视为针对特定环境进行验证、测试或专家审查的替代品。
• 如果缺少必需的输入、权限、安全边界或成功标准，请停止并请求澄清。