windows系统默认max_path限制为260字符，导致composer报“file path too long”错误；根本解决需启用长路径支持：通过设置→系统→高级中开启开关，或正确修改注册表hkey_local_machinesystemcurrentcontrolsetcontrol ilesystem下longpathsenabled为dword值1并重启，且新进程才生效。
composer 在 Windows 上报 File path too long 错误，本质是 Windows 默认的 MAX_PATH 限制（260 字符）被突破。这不是 composer 的 bug，而是系统级限制。必须先开启 Windows 长路径支持，否则任何缓存路径、符号链接或 Composer 配置都只是临时绕路，治标不治本。
为什么组策略或注册表改了还不生效？
常见原因不是没改对，而是没“真正启用”：
- 组策略修改后未运行
gpupdate /force，也未重启——改完必须重启或强制刷新策略 - 注册表项
LongPathsEnabled被建在错误位置：必须位于HKEY_LOCAL_MACHINESYSTEMCurrentControlSetControlFileSystem，不能在CurrentUser下 - 值类型写成字符串（
REG_SZ）而非DWORD (32-bit)，或数值填了"1"（带引号字符串）而不是数字1 - 目标应用（如
php.exe或终端）启动于长路径启用前——需关闭所有 CMD/PowerShell/IDE 再重开
Windows 11 25H2 及新版设置入口变了
2025 年起，微软把长路径开关移到图形界面，但很多人还在找 gpedit.msc：
Windows TTS (WSL2)
下载
在 Windows 11 上"直接发声"的 TTS（从 WSL2/TUI 调用 powershell.exe + System.Speech）。适用于用户说"说出来/读出来/语音播报/用TTS"，或反馈"没声音/tts 生成的 mp3 是空的/播不出来"，以及需要中文语音但 OpenClaw 内置 tts 不可用时。
- 按
Win + I打开「设置」→「系统」→「高级」→ 找到「启用长路径」开关，打开它 - 该设置等价于注册表
LongPathsEnabled = 1，无需手动进注册表 - 仍需重启，且仅对新启动的进程生效（旧 CMD 窗口不会自动继承）
Composer 本身能做的有限，别依赖配置绕过
有人试图用 composer config --global cache-dir D:c 缩短缓存路径，或用 mklink 建短链接——这些操作容易引发新问题：
-
cache-dir只影响包缓存，不影响vendor/解压路径，而报错多发生在vendor/层级嵌套后 - 符号链接在 Git Bash / WSL 下行为不一致，
composer install可能跳过链接或报权限错误 -
COMPOSER_HOME改到根目录（如D:c）看似有效，但一旦项目路径本身很长（比如C:UsersNameDocumentsProjects...src...），依然会触发限制 - 真正可靠的 fallback 是 WSL：在 WSL 中运行
composer完全不受 WindowsMAX_PATH影响，且 PHP 环境一致
.NET 应用或自研工具要处理长路径？
如果你在写一个调用 composer 的 .NET 工具，或封装 PHP 脚本，仅改系统设置还不够：
- 必须在应用的
.manifest文件中声明：<longpathaware xmlns="http://schemas.microsoft.com/SMI/2016/WindowsSettings">true</longpathaware> - PHP 自身从 7.4+ 开始默认支持长路径 API，但旧版（如 7.2）即使系统开了，
file_exists()等函数仍可能失败 - 路径传给 PHP 时，避免拼接出超长字符串再传入；优先用
\?前缀（如\?C: erylongpath），该前缀可绕过MAX_PATH检查，但要求路径为绝对路径且无相对符号（..、.）
系统级长路径支持不是“可选优化”，而是 Windows 下现代 PHP 开发的基础设施。没开它，所有基于路径的操作（包括 git clone、npm install、IDE 索引）都可能在深层依赖里突然崩掉——而且错误信息往往不指向根源。
