Composer script中执行含中文的shell命令失败，根本原因是底层shell环境未正确识别UTF-8编码；应显式设置LANG/LC_ALL或CHCP 65001，改用封装脚本或PowerShell调用，避免直接inline中文路径，并在PHP脚本中主动设编码。

Composer script 中执行含中文的 shell 命令失败怎么办

直接在 composer.json 的 scripts 里写含中文路径或参数的 shell 命令，大概率会报错或乱码——根本原因不是 Composer 本身，而是底层 shell 环境默认未正确识别 UTF-8 编码，尤其在 Windows Git Bash 或某些 Linux 终端中更明显。

实操建议：

Workflow Decomposer

工作流任务拆解与模型编排技能。使用场景：(1) 收到复杂工作任务需要拆解为可执行步骤，(2) 需要为不同步骤选择最合适的模型，(3) 需要跟踪工作流进度和模型使用情况，(4) 长时间任务卡住需要问题诊断和解决方案。

下载

• 不要依赖终端当前 locale 自动生效，显式设置环境变量：LANG=zh_CN.UTF-8、LC_ALL=zh_CN.UTF-8（Linux/macOS）或 CHCP 65001（Windows CMD/PowerShell）
• 避免在 scripts 中直接拼接中文字符串，改用封装好的 shell 脚本文件（如 bin/run-with-chinese.sh），并在脚本开头加 #!/usr/bin/env bash 和 set -u
• 如果必须 inline 写命令，用单引号包裹整个命令，并确保 composer 运行时 shell 支持 UTF-8：例如 'sh -c "echo \"你好\" > output.txt"'

Windows 下 Composer script 执行中文路径报错 File not found

常见于命令中引用了含中文的本地 PHP 文件、配置路径或 vendor 工具，比如 php ./工具/生成器.php。Windows 默认 cmd 的代码页是 GBK，而 Composer 启动子进程时可能继承错误编码。

实操建议：

• 优先改用 PowerShell 替代 cmd：在 composer.json 中指定 "script": "powershell -Command \"& './工具/生成器.php'\""
• 若用 Git Bash，确认其启动时已加载 UTF-8：检查 ~/.bashrc 是否有 export LANG=zh_CN.UTF-8，并确保 Git Bash 版本 ≥ 2.35（旧版存在 execv 对中文路径截断 bug）
• 绕过路径问题：把中文路径文件软链接到英文路径下（Windows 可用 mklink），再在 script 中引用英文路径

composer run-script 输出中文乱码或显示为

这不是 Composer 的 bug，而是输出流未被正确解码。PHP 的 proc_open() 默认不设置 stream_context 的 encoding，导致 stdout/stderr 字节流被当作 ISO-8859-1 解析。

实操建议：

• 在自定义 script 对应的 PHP 脚本中，显式设置输出编码：mb_internal_encoding('UTF-8'); 和 ini_set('default_charset', 'UTF-8');
• 避免用 echo 直接输出中文，改用 file_put_contents('php://stdout', "你好\n", FILE_APPEND | LOCK_EX);
• 如果调用的是第三方 CLI 工具（如 php-cs-fixer），确认该工具自身支持 --encoding=utf8 类参数（部分工具需手动开启）

为什么 exec() 在 script 中能跑通，但 composer run-script 就不行

关键差异在于执行上下文：直接运行 php xxx.php 时，PHP 进程继承终端环境；而 composer run-script 会 fork 出新进程，且部分系统（尤其是 CI 环境）会重置 LANG、LC_* 等变量为空值。

实操建议：

• 在 script 定义中强制注入环境变量："my-script": "env LANG=C.UTF-8 LC_ALL=C.UTF-8 php ./scripts/do-something.php"
• 不要信任 getenv('LANG')，在 PHP 脚本里用 putenv('LANG=zh_CN.UTF-8') 主动设置后再执行 shell 操作
• CI 场景（如 GitHub Actions）需额外声明 runner 环境：defaults: run: shell: bash 并在 job step 中先 run: locale -a | grep zh_CN 验证 UTF-8 locale 是否可用

实际调试时，最容易被忽略的是 shell 子进程的 locale 继承链——它既不等于父进程 PHP 的 locale，也不等于你终端里 locale 命令输出的结果。每次出问题，先在 script 里加一行 env | grep -i lang 看看到底传了什么进去。