xxmkl の Blog
技术· 4 分钟阅读

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 传多行补丁

这套结论来自这台机器的实测,不是猜测。遇到类似问题时,先记录环境版本,再对比写入产物,最后再下结论。

相关阅读