必须先启用Windows长路径支持（LongPathsEnabled=1），否则所有操作均为临时缓解；需通过注册表或组策略开启并重启系统，再配合缩短缓存路径、使用--no-scripts/--no-plugins参数或迁移到WSL2环境。
必须先启用 Windows 长路径支持（LongPathsEnabled）
不打开这个开关，其他所有操作都只是临时止痛——PathTooLongException 会在 composer install、composer dump-autoload 甚至 PHP 自身的 include 调用里反复出现。Windows 10 1607+ 和 Server 2016+ 才支持，且需管理员权限。
推荐用注册表方式（家庭版也适用）：
以管理员身份运行 PowerShell，执行：Set-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" -Name "LongPathsEnabled" -Value 1 -Type DWORD
然后**重启终端**（CMD/PowerShell），最好也重启系统。验证是否生效：运行 composer install -vvv，若不再卡在 mkdir(): Invalid argument 或 The filename or extension is too long 就说明开了。
注意：
- 组策略路径是「计算机配置 → 管理模板 → 系统 → 文件系统 → 启用 Win32 长路径」
- 某些旧版 PHP 扩展（如特定版本的 ziparchive）仍可能因底层未适配而失败，这不是 Composer 的问题
- 即使开了，COMPOSER_CACHE_DIR 还是得设短，否则缓存解压阶段就崩了
用 COMPOSER_CACHE_DIR 强制走短路径缓存
Composer 默认把下载的 zip 包缓存在 %LOCALAPPDATA%\Composer\files\，这个路径本身就很接近 260 限（尤其用户名带中文或超长），再叠加包名和内部目录结构，极易触发错误。必须把它挪到根目录级短路径。
在项目根目录下运行（CMD）：set COMPOSER_CACHE_DIR=D:\ccache
或 PowerShell：$env:COMPOSER_CACHE_DIR="D:\ccache"
关键点：
- 盘符选 D:\ 这类物理盘根目录，别用 C:\Users\... 或网络映射盘
- 该变量只对当前终端会话有效；要永久生效，得加进系统环境变量
- 不要手动创建 D:\ccache 目录——Composer 第一次运行时会自动建，手动建反而可能权限不对
- 这个设置不影响 vendor/ 位置，只缩短下载→解压中间环节的路径深度
跳过高风险脚本与插件（--no-scripts --no-plugins）
很多 PathTooLongException 实际发生在 post-install-cmd 或插件执行阶段，比如 hirak/prestissimo 并行下载后解压、或 autoload 生成时遍历整个 vendor/。这些操作会触发大量文件系统调用，路径链更长。
在 Windows 11 上"直接发声"的 TTS（从 WSL2/TUI 调用 powershell.exe + System.Speech）。适用于用户说"说出来/读出来/语音播报/用TTS"，或反馈"没声音/tts 生成的 mp3 是空的/播不出来"，以及需要中文语音但 OpenClaw 内置 tts 不可用时。
临时安装依赖时，直接加参数：composer install --no-scripts --no-plugins
后续需要跑脚本再单独执行：composer run-script post-install-cmd
常见踩坑点：
- --no-dev 不能替代 --no-scripts，dev 依赖删了，脚本还在
- --no-plugins 会禁用所有插件，包括加速类，但稳定性提升明显
- 如果项目用了 classmap-authoritative，它生成的 classmap 文件里全是绝对路径，开长路径前千万别用，否则 autoload 时直接 fail
终极方案：WSL2 中运行 Composer
不是“兼容”，而是换环境。WSL2 的 Linux 内核路径限制是 4096 字符，vendor/ 嵌套再深也不怕。关键是别让 Windows 的 php.exe 和 WSL2 混用。
操作要点：
- 在 WSL2 里单独安装 PHP（比如 Ubuntu 上用 apt install php-cli）
- 把项目目录放在 WSL2 的 /home/xxx/project 下，别挂载 Windows 的 C:\... 盘
- composer install 全程在 WSL2 终端里跑，不要从 Windows 启动
- Windows 下编辑器（如 VS Code）可装 Remote - WSL 插件，无缝连接
注意：
- WSL2 的 composer 和 Windows 的不是同一个二进制，别试图复用
- vendor/ 生成后，PHP-FPM 或 Apache 必须也在 WSL2 里跑，否则跨系统访问文件权限/路径仍可能出错
- 这是最干净的解法，但意味着开发流程要切到 Linux 环境下
最常被忽略的一点：启用 LongPathsEnabled 后，必须确保所有相关进程（PHP、Composer、终端）都是新启动的——旧进程不会自动继承新策略。哪怕只差一次重启，PathTooLongException 就还在那儿等着你。
