“could not authenticate”或“401 unauthorized”主因是凭证未加载或格式错误：auth.json路径须为~/.composer/auth.json（linux/macos）且权限600、编码utf-8、域名端口完全匹配；凭据需用composer config --global命令写入，避免手动编辑出错；ci中须通过composer_auth环境变量注入，不可硬编码。
Composer install报错“Could not authenticate”或“401 Unauthorized”
这不是网络不通，而是凭证根本没被读到或格式不对。Composer在没拿到有效认证时，会静默 fallback 到未授权请求，最终返回 401，而不是提示“请配置 auth.json”。
- 先运行
composer config --global --list | grep -E "(http-basic|github-oauth|gitlab-token)"，如果输出为空，说明凭据压根没加载 - 检查
auth.json是否放在正确路径：~/.composer/auth.json（Linux/macOS）或%APPDATA%Composeruth.json（Windows），项目级则必须和composer.json同目录 - 文件权限必须是
600（Linux/macOS）：chmod 600 ~/.composer/auth.json，否则 Composer 直接跳过 - 用
file -i ~/.composer/auth.json确认编码是charset=utf-8，不是utf-8-with-bom或us-ascii - 域名必须完全一致：如果仓库 URL 是
https://gitlab.internal:8080/myorg/pkg.git，那么auth.json里http-basic的 key 就得是"gitlab.internal:8080"，端口不能省
GitLab 私有包 require 失败，报 “Could not find package”
这通常不是认证问题，而是 Composer 根本没去查你的 GitLab 仓库——它连包名都没匹配上。
-
repositories必须写在项目级composer.json中，全局配置（composer config --global）对私有源无效 - type 必须是
"vcs"，不是"git"、"package"或漏写；URL 必须是带.git后缀的 HTTPS 地址，例如"https://gitlab.example.com/myorg/pkg.git"，不能是网页地址 - 私有包自身
composer.json中的name字段（如"myorg/pkg"）必须和你在require中写的完全一致：大小写、分隔符、vendor 名一个都不能错 - 如果用了
dev-main这类开发版本，项目根composer.json必须显式声明"minimum-stability": "dev"，否则默认过滤掉所有dev-前缀版本
CI/CD 中 composer install 卡住或报 Auth required
本地能跑，CI 报错，90% 是凭据没注入进去，而不是镜像或网络问题。
- 绝对不要把 token 硬编码进脚本或
composer.json；GitHub Actions 中应使用COMPOSER_AUTH环境变量，格式为 JSON 字符串，且优先级最高 - 示例（GitHub Actions）：
COMPOSER_AUTH: '{"http-basic":{"gitlab.example.com":{"username":"${{ secrets.GITLAB_USER }}","password":"${{ secrets.GITLAB_TOKEN }}"}}}' - GitLab CI 中推荐用
before_script写入$CI_PROJECT_DIR/auth.json，再通过COMPOSER_AUTH_PATH=$CI_PROJECT_DIR/auth.json指定路径 - 加
--no-interaction是必须的，但它不解决认证缺失问题；没配好凭据时它会直接报错退出，而不是卡住 - 执行
composer clear-cache再重试——缓存可能锁住旧的失败状态，导致反复失败
私有包装进 vendor 了，但 new XxxClass() 报 Class not found
下载成功 ≠ 自动加载成功。Composer 不会自动扫描私有包里的类，全靠它自己声明的 autoload 配置生成映射。
- 确认私有包的
composer.json包含合法autoload段，例如："psr-4": {"MyOrg\Pkg\": "src/"}；"files"只适合少量函数文件，不能替代命名空间映射 - 路径是相对于私有包根目录的，不是主项目目录——别写成
"src/MyOrg/Pkg/"，那是错的 - 改过私有包的
autoload规则后，在主项目中必须运行composer dump-autoload，否则vendor/composer/autoload_psr4.php不更新 - 如果私有包用了
classmap，确保composer dump-autoload时包含-o（optimize）参数，否则 classmap 不生效
