如何调整Composer全局变量和环境参数？

本文共计1012个文字，预计阅读时间需要5分钟。

在Composer中，若遇到没有全局变量的问题，通常是因为缺少全局配置项。解决这个问题的方法包括：

composer config --global 是唯一安全写法

所有影响行为的参数——比如镜像源、GitHub Token、缓存路径、代理——都必须用 composer config --global（或简写 composer config -g）写入，不能手动改 ~/.composer/config.json（Linux/macOS）或 %APPDATA%\Composer\config.json（Windows）。

• 手动编辑容易 JSON 格式错误，且 Composer 后续操作（如 self-update）可能覆盖它
• 漏掉 --global 参数会默默写进当前项目的 composer.json 的 config 字段，而不是用户级配置
• 验证是否成功：运行 composer config --global --list，看到目标键（如 github-oauth.github.com）才算写对

哪些配置项真能跨项目生效

不是所有 config 键都支持全局作用域。Composer 对不同字段的处理逻辑完全不同：

• 真正稳定全局生效的：github-oauth、http-basic、http-proxy、cache-dir、process-timeout、secure-http——它们控制网络、认证、缓存、超时等底层行为，项目无法覆盖
• 看似全局、实则受限的：minimum-stability、prefer-stable、platform——只在当前目录没有 composer.json 时（例如空目录下执行 composer require）才读全局值；一旦项目存在 composer.json，这些值立刻被忽略
• 完全无效的：autoload、require、scripts——这些根本不在全局配置支持范围内，设了也静默丢弃

COMPOSER_HOME 不是配置项，而是路径开关

COMPOSER_HOME 是一个环境变量，它决定 Composer 全局文件（config.json、auth.json、vendor/bin）存哪。它不存储任何配置值，但一旦设错，所有全局配置都会“找不到家”。

• 必须为绝对路径，不能含 ~、$HOME 或 %USERPROFILE%
• Linux/macOS 示例：export COMPOSER_HOME="/opt/composer"；Windows CMD：set COMPOSER_HOME=C:\tools\composer
• 设完必须新开终端，再用 composer config --global --list 确认 “Global configuration file” 路径是否匹配
• 常见现象：composer global require laravel/installer 成功，但敲 laravel 报 command not found——本质是 COMPOSER_HOME\vendor\bin 没加进 PATH，和配置无关

环境变量插值只在特定字段生效

Composer 支持在 composer.json 中用 ${VAR_NAME} 占位符引用系统环境变量，但仅限明确支持插值的字段，比如：

• config.http-basic：可写成 {"example.com": {"username": "${GIT_USERNAME}", "password": "${GIT_TOKEN}"}}
• repositories[].url：私有 Packagist 地址可写成 "${PRIVATE_REPO_URL}"
• config.process-timeout 这类数值型配置也可用（需确保变量值是数字字符串）
• 不支持插值的字段：config.repos、config.github-protocols、autoload、scripts——写了也白写
• 注意：.env 文件不会被自动加载；vendor/autoload.php 更不参与此过程；变量必须由 shell、CI env 块、Docker --env 等提前注入

最常被忽略的点：项目级 composer.json 中的 config 字段会**整块替换**同名全局配置，不是合并。哪怕你全局配了 github-oauth，只要项目里写了 "config": { "github-oauth": {} }，Token 就立即失效——这种覆盖是静默的，只能靠 composer config --list 对比确认。