Composer拉取私有仓库提示认证失败？凭据保存与配置镜像【进阶】-composer-PHP中文网

composer install 报 401 unauthorized 的根本原因是未提供或未正确识别认证凭据；需确保 github/gitlab token 权限正确（如 read_api+read_repository）、auth.json 位置格式合规、url 协议与凭据类型匹配，并清除缓存验证。

composer拉取私有仓库提示认证失败？凭据保存与配置镜像【进阶】

为什么 `composer install` 突然报 `401 Unauthorized`？

私有 Git 仓库（如 GitHub/GitLab/自建 Gitea）在 Composer 中拉取失败，绝大多数情况不是网络问题，而是凭据失效或未被识别。Composer 默认不缓存 HTTPS 凭据，每次 clone 都会尝试用空凭据访问 —— 这就触发了 401 Unauthorized。SSH 方式虽可免密，但 composer.json 里写的是 HTTPS URL（比如 "git@github.com:user/pkg.git" 被误写成 "https://github.com/user/pkg.git"），也会导致认证跳过 SSH Agent。

检查 composer.json 中的 repositories 条目：URL 协议必须与你配置的凭据方式一致（HTTPS 对应 token/username+password，SSH 对应 id_rsa）
运行 git ls-remote https://github.com/user/private-pkg.git 手动测试，看是否弹出密码提示或直接失败 —— 这比 Composer 报错更早暴露问题
GitHub 已停用密码登录，必须用 Personal Access Token（PAT），且需勾选 repo 权限；GitLab 同理，Token 类型选 deploy token 或 personal access token，权限不低于 read_repository

怎么让 Composer 记住你的 GitHub/GitLab Token？

靠 git config --global credential.helper store 是无效的 —— Composer 不走 Git 的 credential helper 流程，它自己实现了一套凭据管理。正确做法是通过 auth.json 显式声明：

全局配置（推荐）：~/.composer/auth.json，内容为：

{
    "github-oauth": {
        "github.com": "<code>ghp_abc123...</code>"
    },
    "gitlab-token": {
        "gitlab.example.com": "<code>glpat-xyz789...</code>"
    }
}

项目级配置（仅限当前项目）：./auth.json（与 composer.json 同级），Composer 会优先读取它
Token 必须 Base64 编码后填入？不用。直接明文写入即可，Composer 会自动处理传输加密
注意权限：chmod 600 ~/.composer/auth.json，否则 Composer 会拒绝读取并报 Auth config file is not readable

镜像源和私有仓库能共存吗？`repositories` 顺序很关键

可以共存，但 Composer 加载 repositories 是从上到下匹配的，一旦某个仓库声明了 "packagist.org": false，后面所有包都会绕过 Packagist —— 包括你没显式声明的私有包。常见错误是把私有仓库写在 packagist 镜像之后，结果私有包被当成不存在。

Discussion Composer

围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par

下载

正确顺序：先定义私有仓库（type vcs 或 package），再定义镜像（type composer），最后关闭默认源：

"repositories": [
    {
        "type": "vcs",
        "url": "https://github.com/your-org/internal-lib.git"
    },
    {
        "type": "composer",
        "url": "https://packagist.phpcomposer.com"
    },
    {
        "packagist.org": false
    }
]

如果私有包依赖了其他私有包，别指望 Composer 自动递归解析 —— 每个依赖都得在 repositories 里单独列出来，或者统一托管在同一个私有 Packagist 实例中
使用 composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/ 设置全局镜像，不影响私有仓库匹配逻辑，但无法覆盖 repositories 里显式声明的源

`composer update` 时仍卡在认证环节？检查这些隐藏点

即使 auth.json 存在且格式正确，composer update 仍可能卡住，原因往往藏在细节里：

Git 配置污染：git config --get-all url."https://".insteadOf 如果返回了 git@ 前缀，说明 HTTPS 请求被强行转成 SSH —— 此时 Composer 就不会读 auth.json，而去找 SSH key，容易静默失败
PHP cURL 扩展限制：某些企业环境禁用了 curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true)，导致 GitHub 的 302 重定向失败，表现为超时而非 401 —— 可临时加 -vvv 查看完整请求链路
Composer 版本差异：2.2+ 支持 gitlab-token，但 2.1 及更早只认 gitlab-domains 和 gitlab-token 的旧写法，升级前先确认版本：composer --version
私有域名证书问题：若用自签名证书的 Gitea/GitLab，需在 auth.json 中加 "ssl": {"verify_peer": false}（仅限内网调试，生产环境务必配可信证书）