Composer私有仓库认证失败主因是凭据未正确配置，应使用composer config命令写入auth.json，确保域名、协议、权限（600）及CI环境安全注入均符合规范。
私有仓库认证失败时，composer install 报 401 Unauthorized
私有 Packagist（如 Satis、Private Packagist、GitLab Package Registry）要求 HTTP Basic Auth 或 OAuth Token，但 Composer 默认不传凭据，直接 401。这不是网络问题，是凭据没塞对地方。
实操建议：
- 用
composer config写入全局或项目级凭据，别手动改auth.json文件（容易格式错、权限错） - 对 GitLab / GitHub 私有包，优先走
git协议 + SSH 密钥，而非 HTTPS + 用户名密码（后者在 Composer 中需额外配置http-basic） - 若用 Satis，确保
auth.json里写的是 Satis 服务的访问地址，不是 Git 地址 —— 比如 Satis 部署在https://packages.example.com，就配这个域名，不是git@example.com
auth.json 文件位置和权限必须严格匹配 Composer 行为
Composer 查找 auth.json 有固定顺序：当前项目根目录 → COMPOSER_HOME 目录（通常是 ~/.composer 或 ~/Library/Application Support/Composer），且只读一次。写错位置等于没写。
实操建议：
- 运行
composer config --global --auth http-basic.packages.example.com username token，让 Composer 自动写到正确位置并设好权限（600） - 手动创建
auth.json时，必须用双引号包裹键名和字符串值，不能用单引号；顶层必须是 JSON 对象，不能是数组 - Linux/macOS 下，确认文件属主是当前用户，且权限 ≤
600；否则 Composer 会静默忽略该文件
Satis 配置中 require 的包来源和 repositories 必须对齐
常见现象：Satis 构建成功，packages.json 里也有包信息，但 composer require vendor/package 找不到 —— 因为项目 composer.json 没声明 Satis 仓库，或者声明了但 URL 少了结尾斜杠，导致重定向后凭据丢失。
实操建议：
- 在项目
composer.json的repositories里显式加一条：{"type": "composer", "url": "https://packages.example.com/"}注意末尾/，Satis 重定向依赖它 - 不要把 Satis 仓库设成
packagist.org的替代（"packagist.org": false），除非你真不需要任何公开包；否则应保留默认，并仅追加私有源 - 如果 Satis 后端是 Nginx，检查是否转发了
Authorization头；Apache 默认不传，需加SetEnvIf Authorization "(.*)" HTTP_AUTHORIZATION=$1
CI 环境下凭据注入必须避开 auth.json 明文落盘
GitHub Actions、GitLab CI 里直接 echo '{...}' > auth.json 会导致密钥泄露进日志或缓存；而且 CI runner 往往复用 COMPOSER_HOME，不同项目凭据可能冲突。
实操建议：
- 用
composer config --auth命令动态注入，配合环境变量：composer config --auth http-basic.packages.example.com "$USERNAME" "$TOKEN" - GitHub Actions 推荐用
composer/setup-phpaction，它内置凭据安全注入逻辑；GitLab CI 可用before_script动态生成临时auth.json并设COMPOSER_AUTH环境变量 -
COMPOSER_AUTH环境变量内容必须是合法 JSON 字符串（如{"http-basic":{"packages.example.com":{"username":"u","password":"t"}}}），不是文件路径
