必须用composer config --global命令写入全局配置，因其自动校验JSON格式、处理转义、维护键序并刷新缓存；手改~/.composer/config.json易因格式错误或路径优先级问题导致静默失效。
全局配置必须用 composer config --global 命令写入，手改 config.json 文件几乎必然出错。
为什么不能直接编辑 ~/.composer/config.json
Composer 对 JSON 格式极其敏感：少一个逗号、多一个中文引号、路径里漏了转义斜杠，都会导致后续所有命令静默失败，报错却只显示 file_get_contents(): Failed to open stream 这类无关信息。新版 Composer（2.2+）还会在解析失败时跳过整个文件，不提示、不警告。更麻烦的是，Linux/macOS 下可能同时存在 ~/.composer/config.json 和 ~/.config/composer/config.json，而 Composer 优先读后者——你改了前者，等于白改。
composer config --global 的硬性规则
漏掉 --global（或简写 -g）就写进当前项目 composer.json，不是全局生效。值含空格或特殊字符必须用英文双引号包裹，例如：composer config --global cache-dir "/data/composer-cache"。嵌套键不能一次设全，比如配私有仓库要分两步：composer config --global repositories.myrepo.type "composer" 和 composer config --global repositories.myrepo.url "https://my-repo.example.com"。
哪些配置适合全局设，哪些绝对不能碰
只该设「环境强相关、项目无关」的项：
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
-
repos.packagist（换阿里云/腾讯镜像） -
github-oauth.github.com（防 GitHub 限流） -
cache-dir（指向 SSD 或 Docker volume 路径） -
process-timeout（设为600比0更可靠） -
store-auths（保存私有源密码）
严禁全局设这些项目契约型配置：autoload、scripts、require、minimum-stability——它们全局写了也无效，还可能误导新人以为生效了。
composer global require 装完命令却用不了？PATH 没加对
composer global require laravel/installer 只是把二进制文件放进 COMPOSER_HOME/vendor/bin（Linux/macOS 默认是 ~/.composer/vendor/bin，Windows 是 %APPDATA%\Composer\vendor\bin），它不会自动加进系统 PATH。验证方式很简单：运行 composer config --global home 看路径，再确认该路径是否真的在 PATH 里。Linux/macOS 用户要在 ~/.zshrc 或 ~/.bashrc 末尾加 export PATH="$HOME/.composer/vendor/bin:$PATH"，然后 source ~/.zshrc；Windows 用户得进“系统属性 → 环境变量”，把 %APPDATA%\Composer\vendor\bin 加进用户或系统级 PATH，加完必须新开终端。
最常被忽略的点是：改了 COMPOSER_HOME 环境变量后，没重启终端，composer config --global 写入的仍是旧路径；或者 Windows 用户在 PowerShell 里直接写 %APPDATA%，没展开成完整路径，命令会静默失败。
