必须先启用Windows长路径支持，否则其他操作均属临时绕行且可能无效；需在Windows 10 1607+/Server 2016+中通过组策略或注册表（LongPathsEnabled=1）开启并重启系统。
必须先启用Windows长路径支持
不开启这个系统级开关，其他所有操作都只是临时绕路，甚至可能无效。Windows 10 1607+ 和 Windows Server 2016+ 支持该功能，但默认关闭。
以管理员身份运行 gpedit.msc → 计算机配置 → 管理模板 → 系统 → 文件系统 → 启用「启用 Win32 长路径」
家庭版用户改用注册表：HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem 下新建或修改 LongPathsEnabled（DWORD），值设为 1
修改后必须重启终端（CMD/PowerShell/Git Bash）或整个系统——旧进程不会自动加载新策略
缩短项目基础路径比改配置更直接有效
即使开了长路径，C:\Users\YourName\Documents\GitHub\my-project\vendor\... 这类路径仍可能触发 PHP 扩展（如 ziparchive）、IDE 或 Git 的隐式限制。
把项目移到极短路径下，例如：
-
D:\p\myapp（推荐） -
C:\a（有效，但注意不要和系统目录冲突）
避免以下路径：
- 含中文、空格、括号的父目录名
-
OneDrive、Google Drive等同步文件夹（自带长前缀） - 嵌套过深的子目录，如
src/Http/Controllers/Admin/User/Settings/下执行composer install
调整 Composer 缓存与 vendor 目录位置
默认缓存路径（如 %LOCALAPPDATA%\Composer\files\）本身就很深，解压时会叠加出超长临时路径。重定向可立竿见影。
在 Windows 11 上"直接发声"的 TTS（从 WSL2/TUI 调用 powershell.exe + System.Speech）。适用于用户说"说出来/读出来/语音播报/用TTS"，或反馈"没声音/tts 生成的 mp3 是空的/播不出来"，以及需要中文语音但 OpenClaw 内置 tts 不可用时。
全局设置缓存目录：
composer config --global cache-dir "C:/c"
项目级缩短 vendor 目录（慎用）：
composer config vendor-dir "v"
注意：vendor-dir 设为相对路径（如 v）会放在项目内，仍受基础路径影响；设为绝对路径（如 C:/v）才真正脱离项目层级，但需手动确保该路径存在且有写权限
临时生效环境变量（仅当前终端）：
set COMPOSER_CACHE_DIR=D:\ccache
临时绕过高风险阶段的命令参数
某些插件（如 hirak/prestissimo）或脚本（如生成 autoload_classmap.php）会在解压后触发大量文件遍历，极易在深度嵌套中触达系统边界。
安装时跳过这些环节：
-
composer install --no-scripts --no-plugins：先完成基础依赖解压 -
composer dump-autoload：等 vendor 已存在后再生成 autoload，此时路径已“稳定” -
composer install --no-dev --prefer-dist：跳过开发依赖 + 强制用 dist 包（结构更扁平）
不要长期依赖 --no-scripts，它会跳过必要的初始化逻辑（如 Laravel 的 post-root-package-install）
最常被忽略的是重启终端这一步——很多人改完注册表或组策略后直接开新 CMD 就跑 composer install，结果还是报错。系统策略变更需要进程级刷新，不是窗口级。另外，vendor-dir 改到绝对路径虽能缩短顶层路径，但无法阻止某些包内部（如 phpunit/phpunit/tests/_files/very/deep/nested/）的路径膨胀，所以必须配合长路径支持一起用。
