auth.json文件必须位于~/.composer/auth.json（Linux/macOS）或%APPDATA%\Composer\auth.json（Windows），权限严格设为600，否则Composer静默跳过；项目根目录下auth.json默认不生效，域名key须与仓库URL host完全一致。
auth.json 文件位置和权限必须严格匹配
Composer 只在两个固定路径读取 auth.json：Linux/macOS 是 ~/.composer/auth.json，Windows 是 %APPDATA%\Composer\auth.json。项目根目录下的 auth.json 默认不生效（除非用 --auth 显式指定）。
权限错误比内容错误更常见：文件权限不是 600，Composer 就会静默跳过，不报错也不提示。运行 chmod 600 ~/.composer/auth.json 是必做动作。
- GitLab 域名 key 必须和
repositories.url的 host 完全一致，比如gitlab.example.com:8080和gitlab.example.com是两个不同 key - Bitbucket 不认
consumer-key字段，必须用http-basic结构，且 password 字段填 App Password - GitHub 使用
github-oauth配置方式更稳定，auth.json方式容易因大小写或域名拼写失效
vcs 类型仓库的 URL 必须可直接 git clone
type 字段必须是 "vcs"，不能是 "git"、"package" 或留空；写错就静默忽略，不会报错。
URL 必须是能直接执行 git clone 的地址：
- HTTPS 格式：必须以
.git结尾，如https://gitlab.example.com/acme/utils.git；写成https://gitlab.example.com/acme/utils会报No valid composer.json was found - SSH 格式：如
git@gitlab.example.com:acme/utils.git，需确保本地 SSH agent 已加载对应密钥，并可通过ssh -T git@gitlab.example.com测试连通 - 不能把网页地址（如
https://gitlab.example.com/acme/utils/-/tree/main）当仓库 URL
require 包名与私有库 composer.json 的 name 字段必须逐字符一致
Composer 不按 Git 路径推导包名，只严格比对私有库自身 composer.json 中的 name 字段。差一个字符、大小写不一致、分隔符用错，都会导致 Could not find package。
例如私有库根目录 composer.json 写的是：
{"name": "acme/utils"}
那主项目 require 就只能写：
"acme/utils": "dev-main"
- 不能写成
"Acme/utils"、"acme-utils"、"acme/utils-dev"或省略 vendor 段 - 分支名必须加
dev-前缀："dev-main"可行，"main"或"*"会被当成模糊约束，去 Packagist 查找 - 若私有库没打任何 tag，唯一可用版本就是
dev-main（或dev-master，取决于默认分支名）
HTTPS 私有仓库必须配 ssl.cafile 且格式不可出错
内网 GitLab/Bitbucket 若用了自签名或企业 CA 证书，composer install 会卡在 cURL error 60，但 Composer ≥2.5 不会明确提示证书问题——它只是静默 fallback 到系统 CA，然后继续失败。
正确做法是全局配置 ssl.cafile：
- 证书文件必须是 PEM 格式，且只含证书内容（
-----BEGIN CERTIFICATE-----开头），不能有注释、空行或 BOM - 若中间 CA + 根 CA 都需要，用
cat intermediate.pem root.pem > combined.pem合并，顺序不能反 - 必须用
composer config --global ssl.cafile /path/to/combined.pem，项目级配置无效 - 确认 PHP 进程有读权限，尤其在 nginx/php-fpm 环境下，
www-data用户可能无法读取家目录路径
最容易被忽略的是：证书链文件路径写对了、权限也设好了，但文件里混入了 Windows 换行符或编辑器自动添加的 UTF-8 BOM —— 这类细节一出错，Composer 就完全不认。
