根本原因是Composer拉取私有仓库时依赖系统git的SSH环境，而非auth.json；需确保当前用户SSH密钥已加载、~/.ssh/config配置正确、URL为SSH格式且权限一致。
Composer install 时 Git 报 “Permission denied (publickey)” 怎么办
根本原因是 Composer 在拉取 vcs 类型私有仓库（如 GitHub/GitLab SSH 地址）时，会调用系统 git clone，而该操作依赖当前用户 SSH 环境——不是 Composer 自己的权限逻辑，也不是 auth.json 能管的。
常见现象包括：
Failed to clone https://.../repo.git via https, ssh, ...-
Permission denied (publickey)且git ls-remote -h git@github.com:user/repo.git同样失败 - 本地
git clone git@github.com:user/repo.git成功，但composer install失败（说明 Composer 没走你预期的用户环境）
关键判断点：确认你用的是 SSH URL（git@...）还是 HTTPS URL。只有 SSH URL 才走 SSH key；HTTPS URL 则走 auth.json 或 Git 凭据管理器。
实操建议：
智能 Webhook 分发器，支持 GitHub API 回退机制。当 Git 推送失败时，自动路由至 GitHub Contents API。支持重试逻辑、del…
- 运行
ssh -T git@github.com（或对应 Git 服务商域名），验证当前 shell 用户的 SSH key 是否已加载并被接受 - 确保
~/.ssh/config中没有错误的Host别名覆盖，或IdentityFile指向了不存在的私钥 - 如果在 CI/CD（如 GitHub Actions、GitLab CI）中出错，需显式执行
ssh-add $SSH_PRIVATE_KEY（注意权限：私钥文件必须是600） - 避免混用：不要在
repositories.url写git@...，却指望auth.json生效——它对 SSH 完全无效
为什么 composer install 时 git clone 不用我 sudo 配置的 key
因为 composer install 默认以当前 shell 用户身份运行，sudo composer install 是严重错误操作——它会让 vendor/ 下混入 root 所有者文件，后续 composer update 可能只写一半就中断，autoload 生成失败也不报错。
更隐蔽的问题是：即使你用 sudo -u myuser composer install，若该用户没交互式登录过，其 ssh-agent 往往未启动，git 仍无法读取 key。
实操建议：
- 绝对不要用
sudo composer install；所有权限问题都应回归到用户环境配置 - 检查
whoami和ls -l ~/.ssh/id_rsa所属用户是否一致 - CI 环境中，用
eval $(ssh-agent -s)+ssh-add显式载入 key，而非依赖登录态 - 生产部署脚本里，用
su -c "composer install" -s /bin/sh deploy_user确保完整用户上下文
HTTPS 私有仓库配 auth.json 还是报 401？
不是权限没配对，而是 Composer 根本没读到你的 auth.json——它只认全局路径：~/.composer/auth.json（Linux/macOS）或 %APPDATA%\Composer\auth.json（Windows），项目根目录下的 auth.json 完全被忽略。
另一个高频坑：文件权限不对。Linux/macOS 下必须是 600，否则 Composer 静默跳过整个文件。
实操建议：
- 运行
ls -l ~/.composer/auth.json，确认权限是-rw-------；不是就立刻chmod 600 ~/.composer/auth.json -
auth.json顶层键只能是http-basic，不能是github-oauth或gitlab-oauth（后者仅用于 OAuth token 访问 GitHub API，不用于仓库克隆） - 域名必须与仓库 URL 的 host 部分**完全一致**：比如
https://gitlab.example.com:8080/group/repo.git对应的 key 就得是"gitlab.example.com:8080"，少个端口都不行 - 验证是否生效：执行
composer config --global --list | grep github（或其他域名），看有没有输出凭据信息
GitLab 私有包 install 失败，但 git clone 成功
这通常不是权限问题，而是 Composer 对 vcs 仓库的识别机制出了偏差：它需要目标仓库根目录存在合法 composer.json，且其中 name 字段必须与 require 声明的包名**完全一致**（包括大小写、连字符、下划线）。
典型错误：
-
require写"myorg/utils"，但仓库composer.json里是"myorg/Utils" - 分支名没加
dev-前缀，例如写"myorg/sdk": "main"，正确应为"myorg/sdk": "dev-main" - 仓库 URL 缺
.git后缀，如"https://gitlab.example.com/myorg/sdk"→ 应为"https://gitlab.example.com/myorg/sdk.git"
实操建议：
- 先手动
git clone仓库到临时目录，进目录运行composer validate确认composer.json语法和字段合法 - 检查
name字段是否与require中的字符串逐字节相同 - 用
composer install -vvv查看详细日志，重点找Reading composer.json of myorg/sdk (dev-main)这类行——如果没出现，说明根本没扫描到该仓库 - 确认
repositories数组里type: "vcs"的 URL 能被git ls-remote -h正常访问
auth.json，git 走的是哪个用户的 SSH agent，composer install 运行在哪个 UID 下，三者必须对齐。漏掉任意一环，都会表现为“明明配了却没用”。 
