Windows PowerShell 写中文文档和补丁的坑
在 Windows、PowerShell 7 和 Codex CLI 环境下,记录中文 Markdown 写入、UTF-8 编码和 apply_patch 参数传递的实际排障过程。
现象
我在这台 Windows 机器上写中文 Markdown 和执行补丁时,遇到过几类问题:
--codex-run-as-apply-patch requires a UTF-8 PATCH argument.
Invalid patch: The last line of the patch must be '*** End Patch'
“<”运算符保留供将来使用。
一开始容易把问题归因于“中文编码”,但测试后发现:中文本身没问题,真正的问题主要出在 Windows 的命令传参链路。
这台机器的环境
结论必须结合环境看。我这台机器的实测环境是:
| 项目 | 信息 |
|---|---|
| 系统 | Windows |
| Shell | PowerShell 7.6.6 |
| Node.js | 20.17.0 |
| 博客仓库 | 本地 Next.js 博客仓库 |
| 用户目录 | %USERPROFILE% |
| Codex CLI | 安装在用户目录下的 codex.exe |
apply_patch |
一个 .bat 包装器 |
这里最重要的是 PowerShell 7.6.6。Windows PowerShell 5.1 的默认编码行为不同,所以不能把这些结论直接套到 5.1 上。
关键发现一:apply_patch 其实是 .bat
在这台机器上,命令行里的 apply_patch 实际指向一个 .bat 包装器,内容大致是:
@echo off
"%~dp0...\codex.exe" --codex-run-as-apply-patch %*
所以直接执行:
apply_patch $patch
实际链路是:
PowerShell
→ apply_patch.bat
→ cmd 参数解析
→ codex.exe
这个链路对多行补丁、引号、换行和 %~dp0 都不友好。参数传到 Codex CLI 时,已经不是原始字符串。
关键发现二:中文 UTF-8 写入本身没问题
我用这段文本做了测试:
平台不受理以下情形的退款申请:未经钱包充值测试,直接购买套餐,随后以「模型精度低」「模型质量低」「智商差距大」等主观、无据的表述主张退款。
测试结果:
| 写入方式 | 内容一致 | UTF-8 BOM | 包含 CR | 字节长度 |
|---|---|---|---|---|
Set-Content -Encoding utf8NoBOM |
是 | 否 | 是 | 203 |
Out-File 默认编码 |
是 | 否 | 是 | 203 |
Node writeFileSync |
是 | 否 | 是 | 203 |
直接调用 apply_patch.bat |
否 | - | - | 未生成 |
Node spawnSync + Codex CLI |
是 | 否 | 否 | 202 |
结论:
- PowerShell 7 写中文 Markdown 没问题;
Set-Content -Encoding utf8NoBOM可靠;Out-File在 PowerShell 7 中默认也是 UTF-8 无 BOM;- 真正不可靠的是直接给
.bat传多行补丁。
Microsoft 官方文档也确认:PowerShell 7 的 Set-Content 和 Out-File 的 Encoding 参数默认值都是 utf8NoBOM。
推荐写法一:写 Markdown
日常写中文 Markdown,我用:
$content = @'
# 中文标题
平台不受理以下情形的退款申请:未经钱包充值测试,直接购买套餐,随后以「模型精度低」「模型质量低」「智商差距大」等主观、无据的表述主张退款。
'@
Set-Content -LiteralPath .\docs\example.md -Value $content -Encoding utf8NoBOM
优点:
- 显式指定 UTF-8 无 BOM;
- 中文标点、直角引号、顿号都能正常保留;
- 不依赖当前默认编码;
- 适合写文档。
注意:PowerShell here-string 在这台机器上会生成 CRLF,但对 Markdown 来说完全没问题。
推荐写法二:执行补丁
补丁的关键是不要经过 .bat。我把稳定流程封装成了两个脚本。
PowerShell 入口:
.\scripts\Apply-Patch.ps1 -Patch $patch
核心 Node 脚本:
node .\scripts\apply-patch.mjs .\patch.tmp
实际链路:
PowerShell 写 UTF-8 无 BOM 临时补丁
→ Node apply-patch.mjs
→ 解析 apply_patch.bat 中的 codex.exe 绝对路径
→ codex.exe --codex-run-as-apply-patch
这样绕过了 .bat 的参数转换问题。
额外发现:Markdown 反引号也会踩坑
测试过程中,我还把报告写坏过一次。原因是这段 PowerShell:
$report += "- `Set-Content`"
双引号字符串里的反引号被 PowerShell 当成转义符,最终输出变成了乱码。
正确做法:
- Markdown 内容里的反引号使用单引号字符串;
- 长文档用 here-string;
- 不要在双引号字符串里直接写 Markdown 反引号。
这也是为什么我说:中文编码本身没问题,容易出问题的是 PowerShell 的引号、反引号和跨进程参数三者叠加。
最终选择
我的最终结论很简单:
- 写中文 Markdown:PowerShell 7 +
Set-Content -Encoding utf8NoBOM - 执行补丁:UTF-8 补丁文件 + Node
spawnSync+ Codex CLI - 不要:直接从 PowerShell 给 Windows 的
apply_patch.bat传多行补丁
这套结论来自这台机器的实测,不是猜测。遇到类似问题时,先记录环境版本,再对比写入产物,最后再下结论。