私有源认证失败主因是Composer缺失访问凭证，非文件权限问题；常见于auth.json配置错误、Token过期或权限不足、HTTPS证书验证失败及CI环境凭证未注入。
私有源认证失败时，composer install 报 401 Unauthorized 或 403 Forbidden
这不是文件系统权限问题，而是 Composer 没拿到私有仓库（如 GitLab、GitHub Enterprise、Satis、Private Packagist）的访问凭证。错误通常出现在 composer install 读取 composer.lock 中私有包元数据、或尝试下载 ZIP/tarball 时。
常见诱因：
-
auth.json缺失、路径错位（应放在项目根目录或COMPOSER_HOME下），或格式非法（JSON 语法错误、多层嵌套错误） - Token 过期、权限不足（例如 GitHub Token 缺少
read:packages，GitLab Token 缺少apiscope） - 私有源配置在
composer.json里用了http://却没配allow-plugins或跳过 TLS 验证（不推荐） - CI 环境中未注入凭证：比如 GitHub Actions 没用
secrets.COMPOSER_AUTH注入auth.json内容
验证方式：运行 composer config --global github-oauth.github.com（GitHub）或 composer config --list | grep -A5 repositories 查私有源是否注册成功；再手动 curl -H "Authorization: Bearer xxx" https://your-private-repo.com/packages.json 测试 token 是否有效。
auth.json 放哪儿才生效？项目级 vs 全局级优先级怎么算
Composer 查找 auth.json 的顺序是：当前目录 → COMPOSER_HOME（默认 ~/.composer/）→ 系统级（极少见）。项目根目录下的 auth.json 仅对本项目生效，适合含敏感凭证的 CI 临时挂载；全局 auth.json 更常用，但要注意多人共用机器时的泄露风险。
正确写法示例（项目级）：
{
"http-basic": {
"gitlab.example.com": {
"username": "token",
"password": "glpat-xxxxxxxxxxxxxxxxxxxx"
}
},
"github-oauth": {
"github.com": "ghp_xxx..."
}
}
注意：http-basic 的 password 字段填的是 Personal Access Token，不是密码；GitHub 必须用 github-oauth 键，不能塞进 http-basic。
安全提醒：别把 auth.json 提交到 Git。加到 .gitignore；CI 中用环境变量动态生成，例如 GitHub Actions：
- name: Setup auth.json
run: echo '${{ secrets.COMPOSER_AUTH }}' > auth.json
私有源用自签名证书或内网 HTTP，composer install 直接报 SSL 错误
Composer 默认校验 HTTPS 证书，遇到私有 Satis、Artifactory 或测试环境 HTTP 源会直接中断。不要改系统 CA 证书或全局关校验——这会破坏安全性。
精准控制方式：
- 对单个私有源禁用验证（仅限可信内网）：
composer config repositories.my-satis --no-interaction --force-http true https://satis.internal - 若必须用 HTTP（不推荐），先确保
composer.json中该源协议明确为http://，再加"secure-http": false到根配置（注意：Composer 2.2+ 要求显式声明） - 自签名证书场景：把企业 CA 根证书导出为 PEM，用
composer config --global cafile /path/to/company-ca.pem指定，比关校验更安全
执行后检查：composer config --global cafile 或 composer config repositories.my-satis 确认设置已落盘。
Docker 或 CI 中私有源始终 401，但本地能通
根本原因常是环境隔离导致凭证不可见：容器没挂载 ~/.composer/auth.json，或 CI runner 用的是不同用户（UID 不匹配导致文件不可读），或 COMPOSER_HOME 被覆盖却没同步凭证。
务实解法：
- Docker 构建阶段：用
--secret挂载auth.json，并在Dockerfile中复制：RUN --mount=type=secret,id=composer-auth,dst=/tmp/auth.json cp /tmp/auth.json /root/.composer/auth.json - GitHub Actions：用
secrets.COMPOSER_AUTH注入内容，再run: echo "${{ secrets.COMPOSER_AUTH }}" > ~/.composer/auth.json - GitLab CI：定义
COMPOSER_AUTH变量（类型为 File），它会自动映射为文件路径
关键检查点：进容器或 runner 执行 ls -l ~/.composer/auth.json && cat ~/.composer/auth.json，确认文件存在、可读、内容合法——很多问题卡在这一步就结束了。
私有源权限问题的核心从来不在磁盘 rwx，而在「Composer 能否代表你，向远端服务证明你是谁」。token 有效期、scope 权限、证书信任链、环境变量继承，这些环节断一个，401 就稳稳报给你看。
