COMPOSER_HOME必须设绝对路径：Linux/macOS用/home/user/.composer（禁用~或$HOME），Windows用C:\Users\user\AppData\Roaming\Composer（禁用%APPDATA%或中文路径）；设后须重启终端，验证composer config --list --global中“Global configuration file”路径是否匹配，并确保PATH包含$COMPOSER_HOME/vendor/bin或%COMPOSER_HOME%\vendor\bin。
COMPOSER_HOME 路径写法差异：Linux/macOS 与 Windows 的绝对路径陷阱
Linux/macOS 和 Windows 对 COMPOSER_HOME 的路径解析逻辑一致——只认绝对路径，但“绝对”的定义和常见错误完全不同。
- Linux/macOS 必须用
/home/username/.composer这类完整路径，~/.composer或$HOME/.composer会被忽略，Composer 直接退回到默认路径（如~/.config/composer） - Windows 必须用
C:\Users\username\AppData\Roaming\Composer，不能写%APPDATA%\Composer或C:\用户\username\...——中文路径、环境变量占位符、相对路径全失效 - 验证唯一可靠方式是运行
composer config --list --global，看 “Global configuration file” 行输出的路径是否与你设置的一致；不匹配=白设
PATH 配置目标目录不同：不是 composer.bat 所在目录，而是 vendor/bin
很多人把 C:\ProgramData\ComposerSetup\bin 加进 PATH，结果 laravel 命令仍报错。问题不在 Composer 安装本身，而在 PATH 指向了错误位置。
- Linux/macOS 应添加
$COMPOSER_HOME/vendor/bin（新版 Composer 2.4+ 默认在~/.config/composer/vendor/bin，不是~/.composer/vendor/bin） - Windows 应添加
%COMPOSER_HOME%\vendor\bin（若未设COMPOSER_HOME，则为%APPDATA%\Composer\vendor\bin） - 别依赖
composer global config bin-dir --absolute输出后手动拼路径——直接用它作为 PATH 值最安全：export PATH="$(composer global config bin-dir --absolute):$PATH"
环境变量生效机制差异：终端重启 vs source，Windows 用户尤其容易漏掉
Linux/macOS 下 source ~/.zshrc 只影响当前 shell，子进程（如 VS Code 终端、IDE 内置终端）不一定继承；Windows 下系统级变量修改后，旧 CMD/PowerShell 窗口完全不会刷新 PATH。
- Linux/macOS：改完
~/.zshrc后，新开终端比source更可靠；VS Code 用户需完全关闭窗口再重开 - Windows：必须关闭所有已打开的 CMD/PowerShell/终端应用，再新开——
echo %PATH%不出现新路径，说明没生效 - 验证命令：
where composer（Windows）或which composer（macOS/Linux）确认 composer.bat / composer 是否在 PATH 中；where laravel或which laravel确认全局命令是否指向vendor/bin下的真实文件
COMPOSER_AUTH 等敏感变量的跨平台赋值语法不兼容
COMPOSER_AUTH 是少数需要 JSON 字符串值的 Composer 环境变量，但不同 shell 对引号、转义、换行的处理差异极大，直接复制粘贴几乎必错。
- Linux/macOS bash/zsh：必须用单引号包裹整个 JSON，双引号保留在内部：
export COMPOSER_AUTH='{"http-basic": {"repo.example.com": {"username": "u", "password": "p"}}}' - Windows CMD：不用引号，但 JSON 内不能有空格，且等号前后不能有空格：
set COMPOSER_AUTH={"http-basic": {"repo.example.com": {"username": "u", "password": "p"}}} - Windows PowerShell：必须用双引号，且内部双引号要转义：
$env:COMPOSER_AUTH='{\"http-basic\": {\"repo.example.com\": {\"username\": \"u\", \"password\": \"p\"}}}' - CI 场景（如 GitHub Actions）：YAML 中用字符串字面量，避免 shell 解析干扰：
COMPOSER_AUTH: '{"http-basic": {"repo.example.com": {"username": "ci", "password": "${{ secrets.PASS }}"}}}'
实际配置时最容易被忽略的不是“怎么设”，而是“设完是否真被读到”。composer config --list --global 和 echo $PATH/echo %PATH% 必须同时验证，缺一不可；任何一步路径不匹配，全局命令就等于不存在。
