auth.json必须放在~/.composer/auth.json（linux/macos）或%appdata%\composer\auth.json（windows），权限600，顶层键仅支持http-basic，域名须与仓库url完全一致。
auth.json 放哪、权限和字段名怎么写才生效
Composer 不会读取项目根目录下的 auth.json，它只认全局路径：Linux/macOS 是 ~/.composer/auth.json，Windows 是 %APPDATA%\Composer\auth.json。放错位置就等于没配。
文件权限必须是 600：运行 chmod 600 ~/.composer/auth.json，否则 Composer 静默忽略整个文件。
字段名不能写错：http-basic 是唯一合法的顶层 key（不是 github-oauth 或 gitlab-oauth）；域名 key 必须和 repositories.url 中的 host 完全一致（比如 gitlab.example.com:8080 和 gitlab.example.com 是两个不同 key）。
GitLab 示例内容：
{"http-basic": {"gitlab.example.com": {"username": "oauth2", "password": "glpat-xxx"}}}
HTTPS 方式填 URL 时为什么总被跳过
Composer 对 vcs 类型仓库的 url 字段校验极严，填错不会报错，而是直接跳过该仓库——你甚至看不到提示。
常见错误包括：
-
url缺.git后缀，例如写成https://gitlab.example.com/myorg/sdk - 写了 HTML 页面地址，例如
https://gitlab.example.com/myorg/sdk/-/tree/main - 用了已弃用的 token 写法，如
https://token:x-oauth-basic@gitlab.example.com/...（1.10+ 已不支持）
验证是否真正可达：新开终端执行 git ls-remote -h https://gitlab.example.com/myorg/sdk.git，能列出分支才算通过。
SSH 方式为什么 clone 成功但 Composer 仍失败
本地能 ssh -T git@gitlab.example.com 成功，不代表 Composer 就能用 SSH 拉代码——它依赖的是系统级 SSH agent 的环境上下文。
CI/CD 环境尤其容易出问题：
- GitHub Actions 默认不加载 SSH agent，需显式启用
ssh-agent并ssh-add私钥 - Docker 构建中未挂载
~/.ssh或未启动 agent，git clone git@...会卡住或超时 - 私钥密码未清空（passphrase），而 Composer 不支持交互式输入
推荐做法：用 ssh-keygen -N "" -f ~/.ssh/id_rsa 生成无密钥私钥，并确保公钥已添加到 Git 平台的 Deploy Keys（而非用户 SSH Keys），避免权限过大。
require 里写对了包名，但还是报 Could not find package
根本原因不是凭证失效，而是 Composer 默认关闭了 Packagist 的隐式源——哪怕你只加了一条私有 vcs 仓库，它也不会再去查 packagist.org。
解决方法是在 repositories 数组最前面补一条兜底项：
{"type": "composer", "url": "https://packagist.org", "packagist": false}
注意："packagist": false 是显式禁用，不是删掉；不加这条，composer require monolog/monolog 这类公共包也会失败。
另外确认三点：
- 私有库根目录
composer.json里的name字段（如"acme/utils"）必须和require中完全一致，大小写、斜杠、vendor 段都不能差 - 分支名必须加
dev-前缀，"acme/utils": "dev-main"可行，"main"会被当成模糊约束去 Packagist 查 - 标签名要带
v前缀，"v1.2.0"可识别，"1.2.0"不识别
最常被忽略的是兜底源配置和 name 字段的精确匹配——这两点不出错，其他基本都好调。
