diff --git a/Local-Development-and-Verification.-.md b/Local-Development-and-Verification.-.md index 2dd3dd4..e04a8c8 100644 --- a/Local-Development-and-Verification.-.md +++ b/Local-Development-and-Verification.-.md @@ -15,6 +15,60 @@ 不要打印或提交 PAT。 +## Windows PowerShell 与 UTF-8 + +### Shell 选择 + +- 优先使用当前已经配置的 PowerShell;可选择时优先 PowerShell 7 `pwsh.exe`。 +- 只有 PowerShell 7 不可用或命令明确依赖 Windows PowerShell 5.1 时才使用 `powershell.exe`。 +- 不得仅为设置编码重复启动一层 PowerShell;嵌套进程会增加启动时间、转义复杂度和错误定位成本。 +- 代码搜索仍优先使用代码图工具;非代码文本或图工具不足时优先使用 `rg`,不因本节改用 `Select-String`。 + +### 文件编码 + +文件解码与控制台输出编码是不同问题。读取 UTF-8 文本时,在命令支持的情况下显式指定编码和字面路径: + +```powershell +Get-Content -LiteralPath "path\to\file.md" -Encoding utf8 +``` + +仓库文件修改仍使用项目规定的编辑工具;不要为了指定编码改用 shell 拼接、重定向或临时写文件。PowerShell 5.1 与 PowerShell 7 对无 BOM UTF-8 和写入默认值存在差异,不能只凭控制台显示判断文件编码。 + +### 控制台与外部命令输出 + +PowerShell 7 默认通常已满足 UTF-8 场景。只有出现真实乱码,或已知宿主/外部程序没有使用 UTF-8 时,才在当前进程设置: + +```powershell +$OutputEncoding = [Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false) +``` + +确实需要显式启动 PowerShell 7 时使用: + +```powershell +pwsh.exe -NoLogo -NoProfile -NonInteractive -Command '$OutputEncoding = [Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false); <命令>' +``` + +不要把这个包装应用到每条命令;同一会话中已经生效且环境未变化时不重复设置。 + +### Python 中文输出 + +只有 Python 命令已经出现乱码,或运行宿主已知不是 UTF-8 时,才在当前 PowerShell 进程设置: + +```powershell +$env:PYTHONUTF8 = "1" +$env:PYTHONIOENCODING = "utf-8" +python dev_scripts/harness.py check --strict +``` + +这些变量只影响当前进程及其子进程,不写入仓库或全局用户配置。乱码仍存在时,先判断问题来自文件解码、控制台、管道还是外部程序,再处理首个真实原因。 + +### ExecutionPolicy 边界 + +- `Get-Content`、`rg`、Git、Python 和普通 PowerShell cmdlet 不需要 `-ExecutionPolicy Bypass`。 +- 不得默认添加 `-ExecutionPolicy Bypass`,也不得把它写入所有命令的统一包装。 +- 只有已确认可信的 `.ps1`确实被执行策略阻止、任务范围允许执行且没有更小替代方案时,才可对该次进程使用 Bypass,并在工单记录脚本路径、阻止信息和使用原因。 +- Bypass 只解决执行策略阻止,不解决文件编码、控制台编码、权限或脚本自身错误。 + ## 第一次运行 ### 1. 检查工作区