全局配置文件是 ~/.composer/config.json(Linux/macOS)或 %APPDATA%\Composer\config.json(Windows),部分新版本用 ~/.config/composer/config.json;备份该文件即可,auth.json需单独备份,二者缺一不可。

全局配置文件在哪,直接备份哪个路径
Composer 全局配置本质就是 ~/.composer/config.json(Linux/macOS)或 %APPDATA%\Composer\config.json(Windows),它控制着全局仓库源、认证凭据、目录偏好等。部分新版本会用 ~/.config/composer/config.json,执行 composer config -g --list 可确认真实路径。
只备份这个文件就足够了——不需要打包整个 .composer 目录,除非你也想一并迁移缓存(cache/)或插件(vendor/)。缓存可删,插件建议重装,唯独 config.json 是元数据核心。
auth.json 为什么必须单独处理
auth.json 和 config.json 是两个独立文件,都放在同一目录下,但 Composer 加载时互不干扰。前者只管认证(如私有 Git 仓库 token、GitHub OAuth),后者管行为配置(如镜像源、vendor 路径)。漏掉 auth.json,迁移后执行 composer install 会卡在私有包拉取环节,报错类似 Could not authenticate 或 401 Unauthorized。
常见错误操作:只备份 config.json,以为 token 也在里面。实际它从不写入 config.json,必须显式备份 auth.json。
- Linux/macOS:运行
cp ~/.composer/auth.json /backup/ - Windows:手动复制
%APPDATA%\Composer\auth.json - 若
auth.json不存在,说明没配过私有源,跳过即可
迁移时怎么避免“配置生效但行为异常”
直接把 config.json 和 auth.json 复制到新机器的对应路径,看似完成,但容易因环境差异出问题:
- 新机器上
COMPOSER_HOME环境变量可能被设过,导致 Composer 去读别的目录——执行composer config --global home确认输出是否为你预期的路径 - 旧配置里若有已弃用字段(如
fxp-asset插件相关项),新版本 Composer 会静默忽略,但可能掩盖真实问题;建议迁移后运行composer config -g --list检查输出是否干净 - 如果旧配置中设置了
vendor-dir,而新项目依赖默认vendor/,可能导致自动加载失败——这类路径类配置最好在项目级composer.json中覆盖,而非全局强绑
镜像源配置不能靠“删掉就还原”,必须显式写回
很多人误以为删掉 config.json 里的 repo.packagist 字段就能恢复官方源,结果反而触发 fallback 行为,请求发到 packagist.org 却因网络不通失败。Composer 的镜像逻辑不是“有则用,无则退”,而是“显式配置才生效,缺失则走硬编码默认值”,但这个默认值只在全新安装时有效。
安全做法是用命令显式还原:
- 切回官方源:
composer config -g repo.packagist composer https://packagist.org - 切回阿里云镜像:
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/ - 注意键名必须是
repo.packagist(单数),写成repos.packagist不报错但完全不生效
真正难搞的不是备份本身,而是你记不清当初改过哪些字段、有没有加过自定义仓库、或者 auth.json 里混了多个 token。每次迁移前,先跑一遍 composer config -g --list 和 cat ~/.composer/auth.json,把输出存个快照,比事后排查省三小时。











