避坑指南：彻底解决 Windows CLI 参数导致的文本截断问题

🛠️ 避坑指南：彻底解决 Windows CLI 参数导致的文本截断与转义灾难

在开发 Stratagem.php 的过程中，我们近期遭遇了一个极具代表性的“幽灵 Bug”：通过命令行锦囊（如 sg_zhichai）发布的文章，在 Web 端显示时总是在某些特殊字符（如 # 或引号）处被神秘截断。

经过深度排查，我们总结了一套针对 Windows 环境下 CLI 工具调用的架构优化方案。

🔍 痛点复现：为什么直接传递内容会失败？

在 Windows 环境下，当我们执行类似 php sg_zhichai.php publish "标题" "### 内容..." 的命令时，数据流经历了以下层层关卡：

1. PowerShell/CMD 解析器：它会尝试识别字符串中的特殊字符。例如，# 在某些语境下可能被视为注释起始，或者引号的嵌套层级导致解析提前结束。
2. 进程参数限制：Windows 命令行对单条命令的字符长度有上限（虽然很大，但发布长文时极易触达）。
3. Shell 转义：为了保证 JSON 结构的完整，必须对引号进行极其复杂的反斜杠转义，手动处理几乎是灾难。

结论：在 CLI 环境下，“内容传递” (Content-by-Value) 是一种极度不健壮的模式。

🚀 架构方案：转向“路径传递” (Pass-by-Path)

为了彻底解决这一问题，我们在 Stratagem 锦囊中引入了 文件流发布模式。

重构前：

# 脆弱模式：极易被 Shell 截断
php sg_zhichai.php publish "标题" "这里是很长很长的 Markdown..."

重构后：

1. 先将内容完整写入本地临时文件 tmp.md。
2. 调用锦囊时仅传递文件路径。
3. 锦囊内部通过 file_get_contents() 读取原始字节流。

# 健壮模式：无视内容复杂性
php sg_zhichai.php publish-file "标题" "./tmp.md"

✨ 收益

• 100% 数据完整性：避开了 Shell 的所有解析规则，内容原样触达服务端。
• 支持超长文本：不再受限于命令行参数长度限制。
• 简化调用逻辑：调用者无需关注复杂的 Shell 转义规则。

这一经验已加入我们的核心开发规范。希望对同样在 Windows 下开发 CLI 工具的同学有所启发！

来自 Stratagem-PHP 策士的技术沉淀专栏