必须备份auth.json，因其存储私有仓库认证凭据且不参与版本控制；缺失会导致composer install报“Failed to authenticate”等错误，需连同~/.composer/config.json一并备份并确保权限为600。
私有仓库配置必须备份 auth.json
Composer 访问私有 Git 仓库（如 GitLab、GitHub Private、自建 Satis/Artifactory）依赖 auth.json 文件提供凭证。它不随 composer.json 提交，也不在版本控制中，极易被忽略。
该文件通常位于两个位置之一：
-
~/.composer/auth.json（全局，影响所有项目） -
./auth.json（项目根目录，仅作用于当前项目，需手动启用：composer config --auth）
常见错误现象：迁移后 composer install 报错 Could not fetch https://gitlab.example.com/api/v4/projects/…: Failed to authenticate，但 composer.json 和 composer.lock 完全一致——问题就出在 auth.json 缺失或路径不对。
实操建议：
- 用
ls -la ~/.composer/auth.json确认文件存在；若不存在，说明凭据是临时传入（如composer config http-basic.gitlab.example.com token user），这类配置已写入~/.composer/config.json，也得一并备份 - 备份命令示例：
cp ~/.composer/auth.json ~/backup/ && cp ~/.composer/config.json ~/backup/ - 恢复时注意权限：
chmod 600 ~/.composer/auth.json，否则 Composer 会拒绝读取
私有包源定义藏在 composer.json 的 repositories 字段里
私有仓库地址不是全局设置，而是声明在每个项目的 composer.json 中。如果没显式配置 "type": "vcs" 或 "type": "composer" 的 repositories，Composer 根本不会去私有源拉包。
典型配置示例：
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
{
"repositories": [
{
"type": "vcs",
"url": "https://gitlab.example.com/myorg/my-private-lib.git"
},
{
"type": "composer",
"url": "https://satis.example.com"
}
]
}
容易踩的坑：
- 只备份了
composer.json，但没检查repositories是否完整——尤其当使用多层嵌套或条件分支时，部分环境可能动态覆盖此字段 - URL 写了内网地址（如
git@gitlab.internal:/path.git），迁移到新服务器后 DNS 或 SSH 配置未同步，导致 clone 失败 - 用了
"packagist.org": false关闭了官方源，但恢复时忘了加，结果composer install报错找不到基础包（如psr/log）
恢复时不能跳过 composer install，也不能直接复制 vendor/
私有包往往含 post-install-cmd 脚本（如生成 API 客户端、编译前端资源）、平台相关扩展（如 ext-igbinary）、或硬编码路径（autoloader 中的绝对路径）。直接复制 vendor/ 到新机器，90% 概率触发以下错误：
-
Class not found（autoload 未重新生成） -
Failed to open stream: No such file or directory（vendor/bin/下脚本头行仍指向旧 PHP 路径） -
Package is not installed correctly（post-install-cmd 未执行）
正确做法：
- 先确认新环境已配置好对应 auth（即上文的
auth.json已就位） - 删掉现有
vendor/和composer.lock（如有旧 lock，优先保留；若不确定，用原composer.lock） - 运行
composer install --no-dev（生产环境）或composer install（开发环境） - 若报
failed to clone，检查 SSH key 是否已添加到新机器的~/.ssh/id_rsa并运行过ssh -T git@gitlab.example.com
私有源不可达时的临时绕过方案
紧急恢复但私有 Git 服务暂时宕机？别硬等。可用 --ignore-platform-reqs 和 --no-scripts 组合争取时间，但仅限临时应急：
-
composer install --ignore-platform-reqs --no-scripts：跳过 PHP 版本/扩展校验 + 不执行 post-install-cmd，能强制解包已缓存的私有包（前提是之前成功安装过，且~/.composer/cache未清空） - 更稳妥的长期方案是本地镜像：用
satis或toran-proxy搭建离线私有源，把常用私有包定期同步过去，避免单点故障 - 注意：
--ignore-platform-reqs可能掩盖真实兼容性问题，上线前务必回归标准流程
真正关键的不是备份多少文件，而是确认 auth.json、repositories 声明、以及私有源本身在目标环境是否可达——三者缺一，composer install 就会卡在第一步。
