如何为Composer配置全局环境变量和路径，实现跨项目一致使用？

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

COMPOSER_HOME 必须设置为绝对路径，否则使用 `composer global require` 安装的命令行基本找不到；PATH 中不加 vendor/bin 目录，使用 `laravel` 这样的命令就会永久报错 command not found。

COMPOSER_HOME 路径必须绝对、干净、重启终端才生效

这个环境变量一旦设错，composer global require 会静默把可执行文件装进错误目录，后续所有全局命令都失效，但错误提示里完全不提它。

• COMPOSER_HOME 值不能含 ~、$HOME、%USERPROFILE% —— 比如 ~/composer 或 %APPDATA%\Composer（Windows 系统级变量中用 % 变量是合法的，但 Composer 不认）
• Linux/macOS 正确写法：export COMPOSER_HOME="/home/yourname/.my-composer"；Windows 正确写法（用户级）：setx COMPOSER_HOME "C:\Users\YourName\AppData\Roaming\Composer"
• 设完必须新开终端（source ~/.zshrc 不够，因为 Composer 启动时读的是 shell 初始化前的环境）；验证方式是运行 composer config --list --global，看第一行 “Global configuration file” 路径是否和你设的一致

PATH 要包含 $COMPOSER_HOME/vendor/bin（或等效 Windows 路径）

很多人以为 composer global require laravel/installer 成功后就能直接敲 laravel，其实 Composer 从不碰系统 PATH —— 它只把 laravel 可执行脚本放进 vendor/bin 目录，剩下的全靠你自己加进 PATH。

• Linux/macOS：在 ~/.zshrc 或 ~/.bashrc 末尾加一行：export PATH="$COMPOSER_HOME/vendor/bin:$PATH"（注意顺序，要放前面，避免系统同名命令覆盖）
• Windows：把 %COMPOSER_HOME%\vendor\bin（不是 %APPDATA%\Composer\vendor\bin！除非你没设 COMPOSER_HOME）加进「系统属性 → 高级 → 环境变量」里的用户 PATH
• 改完 PATH 后，必须新开 cmd/PowerShell/终端；可用 echo $PATH 或 echo %PATH% 确认路径已存在；再运行 which laravel 或 where laravel 看是否指向 vendor/bin 下的文件

全局配置项不是所有都真“全局”，有些只在项目有 composer.json 时才继承

比如 composer config -g minimum-stability dev 看似设了，但在空目录下直接 composer require monolog/monolog，它仍按 stable 处理 —— 因为这个值只在当前项目 composer.json 里没写 "minimum-stability" 字段时才继承。

• 真正稳定全局生效的：网络类配置，如 github-oauth、http-proxy、secure-http、process-timeout
• 容易误判“已生效”的：平台约束类（platform）、稳定性策略（minimum-stability、prefer-stable）、仓库开关（repositories.packagist）—— 它们会被项目级 config 字段整块覆盖，且不 merge
• 查实际生效值：对比 composer config --list --global 和 composer config --list 输出，只有带 (global) 标记的才是当前起作用的全局值

镜像源配置要用 repos.packagist，别用旧的 repo.packagist

很多教程还教 composer config -g repo.packagist https://packagist.laravel-china.org，这在新版 Composer（2.2+）里已无效，会导致 Could not find package 或无限卡在 “Loading composer repositories”。

• 正确键名是 repos.packagist（复数 repos），值必须是 composer 类型 + 完整 URL：composer config -g repos.packagist composer https://packagist.laravel-china.org
• 设完立刻验证：进任意空目录，运行 composer show packagist/support，能快速返回结果说明镜像生效；若超时或报 404，则大概率键名或 URL 错了
• 国内推荐镜像目前是 Laravel China 提供的 https://packagist.laravel-china.org（截至 2026 年 4 月仍在维护），旧的 phpcomposer.com 已停用

最常被跳过的动作是：设完 COMPOSER_HOME 或 PATH 后不新开终端，以及镜像键名写成单数 repo。这两处一错，其余全白配。